Docker¶

Local development environment via Docker Compose with hot reload for all services.

Services¶

docker-compose.yml defines the full development stack:

Service	Image	Port	Purpose
`db`	`postgres:16-alpine`	5432	PostgreSQL database
`redis`	`redis:7-alpine`	6379	Celery broker + cache
`web`	Custom build	8000	Django API server
`worker`	Custom build	—	Celery worker
`beat`	Custom build	—	Celery beat scheduler
`frontend`	Custom build	5173	Admin dashboard (Vite dev)
`portal`	Custom build	5174	Borrower portal (Vite dev)
`docs`	Custom build	8001	MkDocs dev server

Quick Start¶

# Start all services
docker compose up -d

# Start specific services
docker compose up -d db redis web

# View logs
docker compose logs -f web

# Stop all services
docker compose down

Database Configuration¶

db:
  image: postgres:16-alpine
  environment:
    POSTGRES_DB: lms
    POSTGRES_USER: lms
    POSTGRES_PASSWORD: lms
  ports:
    - "5432:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data

Data persists across container restarts via the postgres_data named volume.

Web Service¶

uv run gunicorn config.asgi:application \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --reload

--reload enables hot reload for Python code changes
Source code is volume-mounted for live editing
Connects to db and redis services via Docker networking

Health Check¶

healthcheck:
  test: curl -f http://localhost:8000/api/v1/health || exit 1
  interval: 30s
  timeout: 5s
  start_period: 10s
  retries: 3

Port Mapping¶

Port	Service	URL
5432	PostgreSQL	`postgres://lms:lms@localhost:5432/lms`
6379	Redis	`redis://localhost:6379`
8000	Django API	`http://localhost:8000/api/v1/`
5173	Admin dashboard	`http://localhost:5173/`
5174	Borrower portal	`http://localhost:5174/`
8001	Documentation	`http://localhost:8001/`

Volume Mounts¶

Source code directories are mounted into containers for hot reload:

./backend → /app/backend (web, worker, beat)
./frontend/admin → /app/frontend/admin (frontend)
./frontend/borrower → /app/frontend/borrower (portal)
./docs → /app/docs (docs)

Environment Variables¶

All services read from a .env file in the project root. Copy the example:

cp .env.example .env

Key variables for Docker:

DATABASE_URL=postgres://lms:lms@db:5432/lms
CELERY_BROKER_URL=redis://redis:6379/1
CELERY_RESULT_BACKEND=redis://redis:6379/2
DJANGO_SETTINGS_MODULE=config.settings.development

Note

Docker service names (db, redis) are used as hostnames, not localhost.

Common Operations¶

# Run migrations
docker compose exec web uv run python manage.py migrateschema -as

# Run backend tests
docker compose exec web uv run pytest

# Open Django shell
docker compose exec web uv run python manage.py shell

# Install new Python dependencies
docker compose exec web uv sync --extra dev

# Install new npm dependencies
docker compose exec frontend npm install

Troubleshooting¶

Database connection refused¶

# Ensure db service is running and healthy
docker compose ps db
docker compose logs db

Redis connection issues¶

# Check Redis is accepting connections
docker compose exec redis redis-cli ping

Stale containers¶

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

# Remove all containers and volumes
docker compose down -v