TBank-Backend/docs/user-guide/configuration/docker-setup.md

Docker Setup

Learn how to configure and run the FastAPI Boilerplate using Docker Compose. The project includes a complete containerized setup with PostgreSQL, Redis, background workers, and optional services.

Docker Compose Architecture

The boilerplate includes these core services:

services:
  web:          # FastAPI application (uvicorn or gunicorn)
  worker:       # ARQ background task worker  
  db:           # PostgreSQL 13 database
  redis:        # Redis Alpine for caching/queues
  # Optional services (commented out by default):
  # pgadmin:    # Database administration
  # nginx:      # Reverse proxy
  # create_superuser: # One-time superuser creation
  # create_tier:      # One-time tier creation

Basic Docker Compose

Main Configuration

The main docker-compose.yml includes:

version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    # Development mode (reload enabled)
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
    # Production mode (uncomment for production)
    # command: gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
    env_file:
      - ./src/.env
    ports:
      - "8000:8000"
    depends_on:
      - db
      - redis
    volumes:
      - ./src/app:/code/app
      - ./src/.env:/code/.env

  worker:
    build:
      context: .
      dockerfile: Dockerfile
    command: arq app.core.worker.settings.WorkerSettings
    env_file:
      - ./src/.env
    depends_on:
      - db
      - redis
    volumes:
      - ./src/app:/code/app
      - ./src/.env:/code/.env

  db:
    image: postgres:13
    env_file:
      - ./src/.env
    volumes:
      - postgres-data:/var/lib/postgresql/data
    expose:
      - "5432"

  redis:
    image: redis:alpine
    volumes:
      - redis-data:/data
    expose:
      - "6379"

volumes:
  postgres-data:
  redis-data:

Environment File Loading

All services automatically load environment variables from ./src/.env:

env_file:
  - ./src/.env

The Docker services use these environment variables:

• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB for database
• REDIS_*_HOST variables automatically resolve to service names
• All application settings from your .env file

Service Details

Web Service (FastAPI Application)

The web service runs your FastAPI application:

web:
  build:
    context: .
    dockerfile: Dockerfile
  # Development: uvicorn with reload
  command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
  # Production: gunicorn with multiple workers (commented out)
  # command: gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
  env_file:
    - ./src/.env
  ports:
    - "8000:8000"  # Direct access in development
  volumes:
    - ./src/app:/code/app  # Live code reloading
    - ./src/.env:/code/.env

Key Features:

• Development mode: Uses uvicorn with --reload for automatic code reloading
• Production mode: Switch to gunicorn with multiple workers (commented out)
• Live reloading: Source code mounted as volume for development
• Port exposure: Direct access on port 8000 (can be disabled for nginx)

Worker Service (Background Tasks)

Handles background job processing with ARQ:

worker:
  build:
    context: .
    dockerfile: Dockerfile
  command: arq app.core.worker.settings.WorkerSettings
  env_file:
    - ./src/.env
  depends_on:
    - db
    - redis
  volumes:
    - ./src/app:/code/app
    - ./src/.env:/code/.env

Features:

• Runs ARQ worker for background job processing
• Shares the same codebase and environment as web service
• Automatically connects to Redis for job queues
• Live code reloading in development

Database Service (PostgreSQL 13)

db:
  image: postgres:13
  env_file:
    - ./src/.env
  volumes:
    - postgres-data:/var/lib/postgresql/data
  expose:
    - "5432"  # Internal network only

Configuration:

• Uses environment variables: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
• Data persisted in named volume postgres-data
• Only exposed to internal Docker network (no external port)
• To enable external access, uncomment the ports section

Redis Service

redis:
  image: redis:alpine
  volumes:
    - redis-data:/data
  expose:
    - "6379"  # Internal network only

Features:

• Lightweight Alpine Linux image
• Data persistence with named volume
• Used for caching, job queues, and rate limiting
• Internal network access only

Optional Services

Database Administration (pgAdmin)

Uncomment to enable web-based database management:

pgadmin:
  container_name: pgadmin4
  image: dpage/pgadmin4:latest
  restart: always
  ports:
    - "5050:80"
  volumes:
    - pgadmin-data:/var/lib/pgadmin
  env_file:
    - ./src/.env
  depends_on:
    - db

Usage:

• Access at http://localhost:5050
• Requires PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD in .env
• Connect to database using service name db and port 5432

Reverse Proxy (Nginx)

Uncomment for production-style reverse proxy:

nginx:
  image: nginx:latest
  ports:
    - "80:80"
  volumes:
    - ./default.conf:/etc/nginx/conf.d/default.conf
  depends_on:
    - web

Configuration: The included default.conf provides:

server {
    listen 80;
    
    location / {
        proxy_pass http://web:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

When using nginx:

1. Uncomment the nginx service
2. Comment out the ports section in the web service
3. Uncomment expose: ["8000"] in the web service

Initialization Services

Create First Superuser

create_superuser:
  build:
    context: .
    dockerfile: Dockerfile
  env_file:
    - ./src/.env
  depends_on:
    - db
    - web
  command: python -m src.scripts.create_first_superuser
  volumes:
    - ./src:/code/src

Create First Tier

create_tier:
  build:
    context: .
    dockerfile: Dockerfile
  env_file:
    - ./src/.env
  depends_on:
    - db
    - web
  command: python -m src.scripts.create_first_tier
  volumes:
    - ./src:/code/src

Usage:

• These are one-time setup services
• Uncomment when you need to initialize data
• Run once, then comment out again

Dockerfile Details

The project uses a multi-stage Dockerfile with uv for fast Python package management:

Builder Stage

FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS builder

ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy

WORKDIR /app

# Install dependencies (cached layer)
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project

# Copy and install project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-editable

Final Stage

FROM python:3.11-slim-bookworm

# Create non-root user for security
RUN groupadd --gid 1000 app \
    && useradd --uid 1000 --gid app --shell /bin/bash --create-home app

# Copy virtual environment from builder
COPY --from=builder --chown=app:app /app/.venv /app/.venv

ENV PATH="/app/.venv/bin:$PATH"
USER app
WORKDIR /code

# Default command (can be overridden)
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

Security Features:

• Non-root user execution
• Multi-stage build for smaller final image
• Cached dependency installation

Common Docker Commands

Development Workflow

# Start all services
docker compose up

# Start in background
docker compose up -d

# Rebuild and start (after code changes)
docker compose up --build

# View logs
docker compose logs -f web
docker compose logs -f worker

# Stop services
docker compose down

# Stop and remove volumes (reset data)
docker compose down -v

Service Management

# Start specific services
docker compose up web db redis

# Scale workers
docker compose up --scale worker=3

# Execute commands in running containers
docker compose exec web bash
docker compose exec db psql -U postgres
docker compose exec redis redis-cli

# View service status
docker compose ps

Production Mode

To switch to production mode:

1. Enable Gunicorn:

   # Comment out uvicorn line
   # command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   # Uncomment gunicorn line
   command: gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
   

2. Enable Nginx (optional):

   # Uncomment nginx service
   nginx:
     image: nginx:latest
     ports:
       - "80:80"
   
   # In web service, comment out ports and uncomment expose
   # ports:
   #   - "8000:8000"
   expose:
     - "8000"
   

3. Remove development volumes:

   # Remove or comment out for production
   # volumes:
   #   - ./src/app:/code/app
   #   - ./src/.env:/code/.env
   

Environment Configuration

Service Communication

Services communicate using service names:

# In your .env file for Docker
POSTGRES_SERVER=db      # Not localhost
REDIS_CACHE_HOST=redis  # Not localhost
REDIS_QUEUE_HOST=redis
REDIS_RATE_LIMIT_HOST=redis

Port Management

Development (default):

• Web: localhost:8000 (direct access)
• Database: localhost:5432 (uncomment ports to enable)
• Redis: localhost:6379 (uncomment ports to enable)
• pgAdmin: localhost:5050 (if enabled)

Production with Nginx:

• Web: localhost:80 (through nginx)
• Database: Internal only
• Redis: Internal only

Troubleshooting

Common Issues

Container won't start:

# Check logs
docker compose logs web

# Rebuild image
docker compose build --no-cache web

# Check environment file
docker compose exec web env | grep POSTGRES

Database connection issues:

# Check if db service is running
docker compose ps db

# Test connection from web container
docker compose exec web ping db

# Check database logs
docker compose logs db

Port conflicts:

# Check what's using the port
lsof -i :8000

# Use different ports
ports:
  - "8001:8000"  # Use port 8001 instead

Development vs Production

Development features:

• Live code reloading with volume mounts
• Direct port access
• uvicorn with --reload
• Exposed database/redis ports for debugging

Production optimizations:

• No volume mounts (code baked into image)
• Nginx reverse proxy
• Gunicorn with multiple workers
• Internal service networking only
• Resource limits and health checks

Best Practices

Development

• Use volume mounts for live code reloading
• Enable direct port access for debugging
• Use uvicorn with reload for fast development
• Enable optional services (pgAdmin) as needed

Production

• Switch to gunicorn with multiple workers
• Use nginx for reverse proxy and load balancing
• Remove volume mounts and bake code into images
• Use internal networking only
• Set resource limits and health checks

Security

• Containers run as non-root user
• Use internal networking for service communication
• Don't expose database/redis ports externally
• Use Docker secrets for sensitive data in production

Monitoring

• Use docker compose logs to monitor services
• Set up health checks for all services
• Monitor resource usage with docker stats
• Use structured logging for better observability

The Docker setup provides everything you need for both development and production. Start with the default configuration and customize as your needs grow!