Docker Best Practices

# =============================================================================
# Docker Compose -- Local Development Environment
# =============================================================================
# Services:
#   - backend:  FastAPI application with hot reload (port 8000)
#   - frontend: React dev server with hot reload (port 3000)
#   - db:       PostgreSQL 16 with health check (port 5432)
#   - redis:    Redis 7 with health check (port 6379)
#
# Usage:
#   docker compose up -d          # Start all services
#   docker compose logs -f backend # Follow backend logs
#   docker compose down -v         # Stop and remove volumes
# =============================================================================

services:
  # ─── Backend (FastAPI) ───────────────────────────────────────────────────
  backend:
    build:
      context: .
      dockerfile: Dockerfile.backend
      target: builder  # Use builder stage for dev (includes build tools)
    container_name: app-backend
    ports:
      - "8000:8000"
    volumes:
      # Mount source code for hot reloading
      - ./src:/app/src:cached
      - ./alembic:/app/alembic:cached
      - ./alembic.ini:/app/alembic.ini:ro
      # Do NOT mount node_modules or __pycache__
    environment:
      - APP_ENV=development
      - DEBUG=true
      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/app_dev
      - REDIS_URL=redis://redis:6379/0
      - SECRET_KEY=dev-secret-key-do-not-use-in-production
      - JWT_SECRET_KEY=dev-jwt-secret-do-not-use-in-production
      - LOG_LEVEL=DEBUG
      - CORS_ORIGINS=http://localhost:3000
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s
    # Override CMD for development: enable auto-reload
    command: >
      uvicorn src.main:app
      --host 0.0.0.0
      --port 8000
      --reload
      --reload-dir src
      --log-level debug
    restart: unless-stopped

  # ─── Frontend (React) ───────────────────────────────────────────────────
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.frontend
      target: deps  # Use deps stage that has node_modules
    container_name: app-frontend
    ports:
      - "3000:3000"
    volumes:
      # Mount source code for hot reloading
      - ./frontend/src:/app/src:cached
      - ./frontend/public:/app/public:cached
      # Preserve node_modules from the image (do not override with host)
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - REACT_APP_API_URL=http://localhost:8000
      - REACT_APP_ENABLE_DEBUG_PANEL=true
      - WATCHPACK_POLLING=true  # Enable polling for file changes in Docker
    depends_on:
      backend:
        condition: service_healthy
    # Run React dev server
    command: npm start
    restart: unless-stopped

  # ─── PostgreSQL ─────────────────────────────────────────────────────────
  db:
    image: postgres:16
    container_name: app-db
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: app_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      # Performance tuning for development
      POSTGRES_INITDB_ARGS: "--data-checksums"
    volumes:
      # Persist database data across restarts
      - pgdata:/var/lib/postgresql/data
      # Optional: initialization scripts
      # - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d app_dev"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

  # ─── Redis ──────────────────────────────────────────────────────────────
  redis:
    image: redis:7-alpine
    container_name: app-redis
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    # Limit memory usage in development
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    restart: unless-stopped

# ─── Named Volumes ──────────────────────────────────────────────────────────
volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local

# ─── Networks ────────────────────────────────────────────────────────────────
# Default network is created automatically by Compose.
# All services can reach each other by service name (e.g., db, redis).

# =============================================================================
# Production Python Multi-Stage Dockerfile
# =============================================================================
# Base: python:3.12-slim (Debian-based, best binary wheel compatibility)
# Pattern: Builder stage installs dependencies, runtime stage copies only what
#          is needed. Final image has no build tools, no pip cache, non-root user.
#
# Build:
#   docker build -t app-backend:latest -f Dockerfile.backend .
#
# Run:
#   docker run -p 8000:8000 --env-file .env app-backend:latest
# =============================================================================

# ---------------------------------------------------------------------------
# Stage 1: Builder -- install Python dependencies
# ---------------------------------------------------------------------------
FROM python:3.12-slim AS builder

WORKDIR /app

# Install build-time system dependencies
# - build-essential: gcc, make (needed for compiling C extensions)
# - libpq-dev: PostgreSQL client headers (needed for psycopg2)
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        build-essential \
        libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Copy only requirements first for better layer caching
# This layer is rebuilt only when requirements.txt changes
COPY requirements.txt .

# Install Python dependencies into /install prefix
# --no-cache-dir: do not store pip cache (saves ~50MB)
# --prefix=/install: isolate packages for clean COPY to runtime stage
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ---------------------------------------------------------------------------
# Stage 2: Runtime -- minimal production image
# ---------------------------------------------------------------------------
FROM python:3.12-slim AS runtime

# Metadata labels (OCI standard)
LABEL org.opencontainers.image.title="app-backend"
LABEL org.opencontainers.image.description="FastAPI backend application"
LABEL org.opencontainers.image.vendor="platform-team"

# Install runtime-only system dependencies
# - libpq5: PostgreSQL client library (runtime only, no headers)
# - curl: needed for HEALTHCHECK
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        libpq5 \
        curl \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
# - No login shell (/sbin/nologin)
# - No home directory created
# - Dedicated group
RUN groupadd -r appuser && \
    useradd -r -g appuser -d /app -s /sbin/nologin appuser

WORKDIR /app

# Copy installed Python packages from builder
COPY --from=builder /install /usr/local

# Copy application code
COPY --chown=appuser:appuser src/ ./src/
COPY --chown=appuser:appuser alembic/ ./alembic/
COPY --chown=appuser:appuser alembic.ini .

# Ensure the app directory is owned by appuser
RUN chown -R appuser:appuser /app

# Switch to non-root user
USER appuser

# Expose the application port
EXPOSE 8000

# Health check: verify the application is responding
# - interval: check every 30 seconds
# - timeout: fail if no response within 10 seconds
# - retries: mark unhealthy after 3 consecutive failures
# - start_period: give the app 15 seconds to start up
HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=15s \
    CMD curl -f http://localhost:8000/health || exit 1

# Run with uvicorn
# - --host 0.0.0.0: bind to all interfaces (required in Docker)
# - --port 8000: match EXPOSE
# - --workers 4: production worker count (adjust based on CPU cores)
# - --access-log: enable access logging
CMD ["uvicorn", "src.main:app", \
     "--host", "0.0.0.0", \
     "--port", "8000", \
     "--workers", "4", \
     "--access-log"]

# =============================================================================
# Production React Multi-Stage Dockerfile
# =============================================================================
# Build stage: node:20-alpine (compile TypeScript, bundle React)
# Runtime stage: nginx:alpine (serve static files, ~7MB base)
#
# Final image contains NO Node.js runtime -- only static HTML/CSS/JS + Nginx.
#
# Build:
#   docker build -t app-frontend:latest -f Dockerfile.frontend ./frontend
#
# Run:
#   docker run -p 8080:8080 app-frontend:latest
# =============================================================================

# ---------------------------------------------------------------------------
# Stage 1: Dependencies -- install node_modules
# ---------------------------------------------------------------------------
FROM node:20-alpine AS deps

WORKDIR /app

# Copy only package files for better layer caching
# This layer is rebuilt only when package.json or lockfile changes
COPY package.json package-lock.json ./

# Install dependencies
# --ignore-scripts: security measure, do not run postinstall scripts
# npm ci: clean install from lockfile (deterministic, faster than npm install)
RUN npm ci --ignore-scripts

# ---------------------------------------------------------------------------
# Stage 2: Builder -- compile and bundle the application
# ---------------------------------------------------------------------------
FROM node:20-alpine AS builder

WORKDIR /app

# Copy node_modules from deps stage
COPY --from=deps /app/node_modules ./node_modules

# Copy source code
COPY . .

# Build the production bundle
# This creates the build/ directory with optimized static assets
RUN npm run build

# ---------------------------------------------------------------------------
# Stage 3: Runtime -- serve with Nginx
# ---------------------------------------------------------------------------
FROM nginx:alpine AS runtime

# Metadata labels
LABEL org.opencontainers.image.title="app-frontend"
LABEL org.opencontainers.image.description="React frontend served by Nginx"
LABEL org.opencontainers.image.vendor="platform-team"

# Create non-root user and group
RUN addgroup -g 1001 -S appgroup && \
    adduser -S appuser -u 1001 -G appgroup

# Copy built static files from builder stage
COPY --from=builder /app/build /usr/share/nginx/html

# Copy custom Nginx configuration
# This handles SPA routing (all paths -> index.html)
COPY nginx.conf /etc/nginx/conf.d/default.conf

# Adjust permissions for non-root Nginx operation
# Nginx needs to write to these directories at runtime
RUN chown -R appuser:appgroup /var/cache/nginx \
                              /var/log/nginx \
                              /etc/nginx/conf.d && \
    touch /var/run/nginx.pid && \
    chown appuser:appgroup /var/run/nginx.pid

# Switch to non-root user
USER appuser

# Use non-privileged port (8080 instead of 80)
EXPOSE 8080

# Health check using wget (available in alpine, unlike curl)
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
    CMD wget -q --spider http://localhost:8080/ || exit 1

# Run Nginx in foreground
CMD ["nginx", "-g", "daemon off;"]

# =============================================================================
# Required: nginx.conf
# =============================================================================
# Place this nginx.conf alongside the Dockerfile:
#
#   server {
#       listen 8080;
#       server_name _;
#       root /usr/share/nginx/html;
#       index index.html;
#
#       # SPA routing: serve index.html for all routes
#       location / {
#           try_files $uri $uri/ /index.html;
#       }
#
#       # Cache static assets aggressively
#       location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
#           expires 1y;
#           add_header Cache-Control "public, immutable";
#       }
#
#       # Security headers
#       add_header X-Frame-Options "SAMEORIGIN" always;
#       add_header X-Content-Type-Options "nosniff" always;
#       add_header X-XSS-Protection "1; mode=block" always;
#       add_header Referrer-Policy "strict-origin-when-cross-origin" always;
#
#       # Gzip compression
#       gzip on;
#       gzip_types text/plain text/css application/json application/javascript
#                  text/xml application/xml application/xml+rss text/javascript;
#   }
# =============================================================================