Chapter 39: Docker Containerization

Docker provides consistent environments from development to production. This chapter covers multi-stage builds for React apps, Docker Compose for local development, and optimization techniques.

Multi-Stage Dockerfile

# Dockerfile
# Stage 1: Install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

# Stage 2: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN corepack enable pnpm && pnpm build

# Stage 3: Production
FROM nginx:alpine AS production
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Image sizes:

• node:20-alpine (deps + build): ~180MB each stage
• nginx:alpine (production): ~40MB final image
• Your app's static files: ~2-10MB

The final image contains only Nginx and your compiled static files. No Node.js, no npm, no source code.

Nginx Configuration for SPA

# nginx.conf
server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    # SPA fallback — serve index.html for all routes
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets aggressively (they have content hashes)
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Don't cache index.html (it references the latest assets)
    location = /index.html {
        expires -1;
        add_header Cache-Control "no-store, no-cache, must-revalidate";
    }

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 1000;

    # 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;
}

Docker Compose for Development

# docker-compose.yml
services:
  # PostgreSQL database
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: taskforge
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  # Redis (for sessions, caching)
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  # MinIO (S3-compatible storage for file uploads)
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio-data:/data

volumes:
  pgdata:
  minio-data:

# Start services
docker compose up -d

# View logs
docker compose logs -f db

# Reset database
docker compose down -v  # -v removes volumes (data)
docker compose up -d

Full-Stack Docker Compose

# docker-compose.prod.yml
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "80:80"
    depends_on:
      - api

  api:
    build:
      context: .
      dockerfile: Dockerfile.api
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/taskforge
      SESSION_SECRET: ${SESSION_SECRET}
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

.dockerignore

node_modules
dist
.git
.env.local
.env.*.local
*.md
.vscode
.idea
coverage
playwright-report
test-results

Build and Run

# Build the production image
docker build -t taskforge-web .

# Run the container
docker run -p 8080:80 taskforge-web

# Build with build args (e.g., API URL)
docker build \
  --build-arg VITE_API_BASE_URL=https://api.taskforge.dev \
  -t taskforge-web .

Summary

• ✅ Multi-stage builds produce minimal production images (~40MB)
• ✅ Nginx serves static files with SPA routing and aggressive caching
• ✅ Docker Compose for local development with PostgreSQL, Redis, MinIO
• ✅ Security headers configured in Nginx
• ✅ .dockerignore keeps build context small