This guide will help you set up your local development environment from scratch.

Prerequisites

Install these tools before proceeding:

Required Software

  1. Python 3.14

    • We also use uv for package management. It will be installed in the next steps.

  2. Node.js 22.21.0

    • Recommended: install via nvm to match project version.
      # Install and use Node 22.21.0 with nvm
nvm install 22.21.0
nvm use 22.21.0
node -v  # should output v22.21.0

  3. Bun

      # Check version
bun --version

# Install on macOS/Linux/WSL
curl -fsSL https://bun.sh/install | bash

  4. Docker Desktop

    • Download from docker.com
    • macOS: Install Docker Desktop for Mac
    • Windows: Install Docker Desktop for Windows (with WSL 2 backend)
    • Linux: Install Docker Engine + Docker Compose
      # Verify installation
docker --version
docker-compose --version

  5. Git

      # Check version
git --version

# Install on macOS
brew install git

# Install on Ubuntu/WSL
sudo apt install git

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@company.com"

  6. pgAdmin or Database Client

  7. Postman

    • Download from postman.com
    • Sign in and join the team workspace
    • Import shared collections

Clone Repository 

  # Clone the main repository
git clone git@github.com:your-org/your-app.git
cd your-app

# Verify you're on the main branch
git branch

Environment Variables Setup

Create a .env file in the project root:

  # Copy the example environment file
cp .env.example .env

Edit .env with your local values:

  # .env file for local development

# Application
APP_NAME="YourApp"
ENVIRONMENT="local"
DEBUG=true
SECRET_KEY="your-secret-key-change-this-in-production"

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/yourapp_dev"
DB_HOST="localhost"
DB_PORT="5432"
DB_USER="postgres"
DB_PASSWORD="postgres"
DB_NAME="yourapp_dev"

# Redis
REDIS_URL="redis://localhost:6379/0"

# Celery
CELERY_BROKER_URL="redis://localhost:6379/0"
CELERY_RESULT_BACKEND="redis://localhost:6379/1"

# API
API_V1_PREFIX="/api/v1"
CORS_ORIGINS=["http://localhost:3000", "http://localhost:5173"]

# JWT Authentication
JWT_SECRET_KEY="your-jwt-secret-change-this"
JWT_ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# External APIs (get from team)
SHOPIFY_API_KEY="your-shopify-api-key"
SHOPIFY_API_SECRET="your-shopify-secret"

# AWS (if needed)
AWS_ACCESS_KEY_ID="your-aws-key"
AWS_SECRET_ACCESS_KEY="your-aws-secret"
AWS_REGION="eu-west-1"
S3_BUCKET="your-bucket-name"

# Email (development)
SMTP_HOST="localhost"
SMTP_PORT="1025"
SMTP_USER=""
SMTP_PASSWORD=""
FROM_EMAIL="noreply@yourapp.com"

# Frontend (Vite with Rolldown/SWC for fast builds)
VITE_API_BASE_URL="http://localhost:8000"

Note: Ask your team lead for actual API keys and secrets.

Docker Compose Setup

We use Docker Compose for local development to run PostgreSQL, Redis, and Celery workers.

Start Services 

  # Start all services (PostgreSQL, Redis, Celery worker)
docker-compose up -d

# View logs
docker-compose logs -f

# Check service status
docker-compose ps

Your docker-compose.yml should look like this (or similar):

  version: '3.8'

services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: yourapp_dev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Verify Services 

  # Test PostgreSQL connection
docker-compose exec db psql -U postgres -c "SELECT version();"

# Test Redis connection
docker-compose exec redis redis-cli ping

Backend Setup (FastAPI)

Install uv

uv is an extremely fast Python package installer and resolver.

  # Install uv using pip
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
source $HOME/.cargo/env
uv --version

Create Virtual Environment 

  # Create virtual environment using uv (faster than venv)
uv venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

# You should see (.venv) in your terminal prompt

Install Dependencies 

  # Install dependencies using uv (much faster than pip)
uv pip install -r requirements.txt

# Install development dependencies
uv pip install -r requirements-dev.txt

Run Database Migrations 

  # Create initial migration (if needed)
alembic revision --autogenerate -m "Initial migration"

# Run migrations
alembic upgrade head

# Verify tables were created
docker-compose exec db psql -U postgres -d yourapp_dev -c "\dt"

Seed Test Data (Optional) 

  # Run seed script
python scripts/seed_data.py

Run the Backend 

  # Start FastAPI development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# API will be available at:
# - http://localhost:8000
# - API docs: http://localhost:8000/docs
# - Alternative docs: http://localhost:8000/redoc

Run Celery Worker (Background Jobs)

Open a new terminal window:

  # Activate virtual environment
source venv/bin/activate

# Start Celery worker
celery -A app.worker worker --loglevel=info

# For development, you can also use:
celery -A app.worker worker --loglevel=debug --pool=solo

Frontend Setup (React + TypeScript)

We use Vite as our build tool, which leverages:

  • Rolldown: Rust-based bundler (faster than Webpack)
  • SWC: Rust-based TypeScript compiler (20x faster than Babel)
  • Biome: Rust-based linter and formatter (25x faster than ESLint + Prettier)

This gives us lightning-fast hot reload and build times.

Install Dependencies 

  # Navigate to frontend directory
cd frontend

# Install dependencies using Bun (much faster than npm)
bun install

Run the Frontend 

  # Start Vite development server
bun run dev

# Frontend will be available at:
# - http://localhost:5173 (Vite default with instant HMR)
# Hot Module Replacement (HMR) updates instantly without page refresh

Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit. This is mandatory.

  # Install pre-commit
uv pip install pre-commit

# Install hooks
pre-commit install

# Test hooks on all files
pre-commit run --all-files

You should see output like:

  ruff....................................................................Passed
ty......................................................................Passed
biome...................................................................Passed
bandit..................................................................Passed
trailing-whitespace.....................................................Passed

See ../06-tooling/pre-commit-hooks.md for detailed configuration.

Editor Setup

  1. Install VS Code: Download from code.visualstudio.com

  2. Install Required Extensions:

    • Python (Microsoft)
    • Pylance
    • Ruff (Rust-based linter & formatter)
    • Biome (Rust-based JS/TS linter & formatter)
    • GitLens
    • Docker
    • SQLTools PostgreSQL
    • Bun for VS Code

  3. Install Recommended Settings:

Create .vscode/settings.json in your project:

  {
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": "always"
  },
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "always"
    }
  },
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

See ../06-tooling/editor-setup.md for complete setup.

Configure Linters

Python (pyproject.toml)

Python tooling is configured in pyproject.toml:

  • Ruff: Linting and formatting (replaces Black, isort, flake8)
  • ty: Type checking (replaces mypy)

See ../04-templates/pyproject.toml for configuration.

TypeScript/JavaScript (biome.json)

JavaScript/TypeScript tooling is configured in biome.json:

  • Biome: All-in-one linting and formatting (replaces ESLint + Prettier)

See ../04-templates/biome.json for configuration.

These are already configured in the repository.

Running Tests

Backend Tests 

  # Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run specific test file
pytest tests/test_users.py

# Run tests in watch mode
ptw

Frontend Tests 

  cd frontend

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Run tests in watch mode
bun test --watch

Verify Everything Works

Use this checklist to verify your setup:

Backend Verification

  • docker-compose ps shows all services running
  • Visit http://localhost:8000/docs - you see FastAPI Swagger docs
  • Visit http://localhost:8000/api/v1/health - returns {"status": "healthy"}
  • pytest runs and all tests pass
  • Pre-commit hooks run when you make a commit

Frontend Verification

  • bun run dev starts without errors
  • Visit http://localhost:5173 - you see the app
  • bun test runs and tests pass
  • Hot reload works when you edit a file

Database Verification

  • Connect to PostgreSQL with pgAdmin:
    • Host: localhost
    • Port: 5432
    • User: postgres
    • Password: postgres
    • Database: yourapp_dev
  • You can see all tables created by migrations

Integration Verification

  • Frontend can call backend APIs
  • Login flow works end-to-end
  • Background jobs process (check Celery worker logs)

Common Setup Issues

Port Already in Use

Symptom: Error: “Address already in use” or “Port 5432 is already allocated”

Solution:

  # Find process using the port
lsof -i :5432  # On macOS/Linux
netstat -ano | findstr :5432  # On Windows

# Stop the process or stop Docker containers
docker-compose down

Database Connection Failed

Symptom: “Could not connect to PostgreSQL”

Solution:

  # Check PostgreSQL is running
docker-compose ps

# Check logs
docker-compose logs db

# Restart database
docker-compose restart db

# Verify connection
docker-compose exec db psql -U postgres -c "SELECT 1"

Virtual Environment Issues

Symptom: ModuleNotFoundError even after installing packages

Solution:

  # Deactivate and reactivate
deactivate
source .venv/bin/activate

# Verify you're using the right Python from the venv
which python
python --version

# Reinstall dependencies with uv
uv pip install -r requirements.txt

Pre-commit Hooks Failing

Symptom: Hooks fail on commit

Solution:

  # Run hooks manually to see errors
pre-commit run --all-files

# Update hooks
pre-commit autoupdate

# Skip hooks in emergency (NOT RECOMMENDED)
git commit --no-verify

Docker Compose Won’t Start

Symptom: Services fail to start

Solution:

  # Stop all containers
docker-compose down

# Remove volumes (WARNING: deletes data)
docker-compose down -v

# Rebuild images
docker-compose build --no-cache

# Start fresh
docker-compose up -d

Bun Modules Issues

Symptom: Frontend won’t start, dependency errors

Solution:

  cd frontend

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

Migration Conflicts

Symptom: Alembic migration fails with “target database is not up to date”

Solution:

  # Check current version
alembic current

# Check migration history
alembic history

# If in development, you can drop and recreate
docker-compose down -v
docker-compose up -d
alembic upgrade head

See ../05-runbooks/common-issues.md for more troubleshooting.

Daily Development Workflow

  1. Start your day:

      # Pull latest changes
git pull origin main

# Start services
docker-compose up -d

# Activate virtual environment
source venv/bin/activate

# Run migrations (if any)
alembic upgrade head

# Start backend
uvicorn app.main:app --reload

  2. In another terminal - start frontend:

      cd frontend
bun run dev

  3. In another terminal - start worker (if working on background jobs):

      source venv/bin/activate
celery -A app.worker worker --loglevel=info

  4. End of day:

      # Stop services to save resources
docker-compose down

Getting Help

Next Steps

Once your environment is running:

  1. Read architecture-overview.md to understand the system
  2. Review ../02-standards/code-standards.md
  3. Try making a small change and creating a PR
  4. Set up Postman collections (see ../06-tooling/api-testing.md)

You’re all set! Happy coding! 🎉