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¶

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

2. Install Dependencies¶

Frontend Dependencies¶

npm install

Backend Dependencies¶

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

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

Documentation Dependencies¶

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:

cp .env.example .env

Edit .env with your configuration:

# 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:

# Install prek
uv tool install prek

# Install hooks
prek install

Running the Application¶

Development Mode¶

Start all services:

npm run dev

This starts:

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

Individual Services¶

Frontend Only¶

cd client
npm run dev

Backend Only¶

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

Documentation¶

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

Access at: http://127.0.0.1:8001

Docker Development¶

# 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¶

# Run all hooks
prek run --all-files

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

Format Code¶

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

# TypeScript/JavaScript
npm run format

Lint Code¶

# Python
flake8 api/ tests/

# TypeScript
npm run lint

Testing¶

Backend Tests¶

# Run all tests
python -m unittest discover tests

# Run specific test
python tests/test_fastapi.py

Frontend Tests¶

npm test

Building for Production¶

Frontend¶

npm run build
# Output: dist/

Backend¶

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

Documentation Build¶

mkdocs build
# Output: site/

Docker Images¶

# 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¶

# 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¶

# Reinstall dependencies
rm -rf node_modules
npm install

# Python
pip install -r api/requirements.txt

Docker Issues¶

# 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):

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