Development Setup¶

Prerequisites¶

Before you begin, ensure you have the following installed:

Node.js 20+ and npm
Python 3.11+
Git
Docker Desktop (optional, for containerized development)
uv (Python package manager)

Installation¶

1. Clone the Repository¶

bash

git clone https://github.com/SvenRelijveld1995/portfolio.git
cd portfolio

2. Install Dependencies¶

Frontend Dependencies¶

bash

npm install

Backend Dependencies¶

bash

# Using uv (recommended)
uv pip install -r api/requirements.txt

# Or using pip
pip install -r api/requirements.txt

Documentation Dependencies¶

bash

uv pip install mkdocs-material mkdocs-mermaid2-plugin \
  mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin

3. Environment Configuration¶

Create a .env file in the project root:

bash

cp .env.example .env

Edit .env with your configuration:

env

# Email Configuration (Required for contact form)
EMAIL_ADDRESS=your-email@gmail.com
EMAIL_PASSWORD=your-gmail-app-password

# Database (Optional)
DATABASE_URL=postgresql://user:password@localhost:5432/portfolio

4. Pre-commit Hooks¶

Install pre-commit hooks for code quality:

bash

# Install prek
uv tool install prek

# Install hooks
prek install

Running the Application¶

Development Mode¶

Start all services:

bash

npm run dev

This starts:

Frontend: http://localhost:5173
Backend: http://localhost:8000

Individual Services¶

Frontend Only¶

bash

cd client
npm run dev

Backend Only¶

bash

cd api
python -m uvicorn main:app --reload --port 8000

Documentation¶

bash

python -m mkdocs serve --dev-addr=127.0.0.1:8001

Access at: http://127.0.0.1:8001

Docker Development¶

bash

# Build and run with Docker Compose
docker-compose up --build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Code Quality¶

Run Pre-commit Checks¶

bash

# Run all hooks
prek run --all-files

# Run specific hooks
prek run black isort flake8 --all-files

Format Code¶

bash

# Python
black api/ tests/
isort api/ tests/

# TypeScript/JavaScript
npm run format

Lint Code¶

bash

# Python
flake8 api/ tests/

# TypeScript
npm run lint

Building for Production¶

Frontend¶

bash

npm run build
# Output: dist/

Backend¶

bash

# No build step required for Python
# Ensure requirements.txt is up to date
pip freeze > api/requirements.txt

Documentation Build¶

bash

mkdocs build
# Output: site/

Docker Images¶

bash

# Build frontend
docker build -f Dockerfile.frontend -t portfolio-frontend .

# Build backend
docker build -f Dockerfile.backend -t portfolio-backend .

Troubleshooting¶

Port Already in Use¶

bash

# Find process using port 5173
lsof -i :5173

# Kill process
kill -9 <PID>

Email Not Sending¶

Verify Gmail App Password is correct
Check EMAIL_ADDRESS and EMAIL_PASSWORD in .env
Ensure 2FA is enabled on Gmail account
Check backend logs for errors

Module Not Found¶

bash

# Reinstall dependencies
rm -rf node_modules
npm install

# Python
pip install -r api/requirements.txt

Docker Issues¶

bash

# Clean up Docker
docker-compose down -v
docker system prune -a

# Rebuild
docker-compose up --build

IDE Setup¶

VS Code¶

Recommended extensions:

ESLint
Prettier
Python
Docker
GitLens

Settings (.vscode/settings.json):

json

{
  "editor.formatOnSave": true,
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black"
}

Next Steps¶

Testing — unit tests, Playwright E2E, pytest, pre-commit hooks
Architecture Overview — how frontend, backend, and Azure fit together
API Endpoints — health check, contact form, CV download

Page history

Field	Value
Last updated	2026-03-20

Changelog

Date	PRs	Summary
2026-03-20	#81	Removed inline Testing section; added link to new testing.md page
2026-03-10	#66	Initial local setup page created