🎼 Docker Compose for Production

Compose in Production

Docker Compose describes a multi-container application in one declarative YAML file. In development you lean on bind-mounted source, hot reload, and plaintext passwords. In production those same conveniences become liabilities — you swap them for pinned images, health checks, resource limits, secrets, and segmented networks.

💡 A useful analogy: Compose is the conductor of an orchestra, coordinating many containers to play together. In rehearsal (dev) you allow improvisation; in the live concert (prod) every entrance is precisely cued and rehearsed for reliability.

Dev → Prod Configuration

Here's a typical development Compose file — optimized for convenience:

# compose.yaml (development)
services:
  web:
    build: ./frontend
    ports: ["3000:3000"]
    volumes:
      - ./frontend:/app        # bind mount for hot reload
      - /app/node_modules
    environment:
      - NODE_ENV=development
    command: npm run dev

  api:
    build: ./backend
    ports: ["4000:4000"]
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:password@db:5432/devdb
    depends_on: [db]

  db:
    image: postgres:16
    ports: ["5432:5432"]        # exposed for local tools
    environment:
      - POSTGRES_PASSWORD=password   # plaintext — fine for dev only
      - POSTGRES_DB=devdb
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

The production version swaps convenience for reliability and security: pinned images, resource limits, health checks, secrets, and a segmented backend network the outside world cannot reach.

# compose.prod.yaml (production)
services:
  web:
    image: ${REGISTRY}/frontend:${TAG}
    deploy:
      replicas: 2
      resources:
        limits: { cpus: '0.5', memory: 512M }
      restart_policy: { condition: any, max_attempts: 3 }
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    networks: [frontend]
    ports: ["80:3000"]
    environment:
      - NODE_ENV=production
      - API_URL=http://api:4000

  api:
    image: ${REGISTRY}/backend:${TAG}
    deploy:
      resources:
        limits: { cpus: '1.0', memory: 1G }
      restart_policy: { condition: any }
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:4000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    networks: [frontend, backend]
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://appuser@db:5432/proddb
    depends_on:
      db: { condition: service_healthy }
    secrets: [db_password]

  db:
    image: postgres:16-alpine
    deploy:
      resources:
        limits: { cpus: '2.0', memory: 2G }
      restart_policy: { condition: any }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data
    networks: [backend]
    environment:
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD_FILE=/run/secrets/db_password
      - POSTGRES_DB=proddb
    secrets: [db_password]

networks:
  frontend:
  backend:
    internal: true          # no route to the outside world

volumes:
  db_data:

secrets:
  db_password:
    file: ./secrets/db_password.txt

Override Files & Profiles

Base + override files

Keep one base file with what's common to every environment, then layer environment-specific overrides on top. Compose merges them left-to-right.

# Files
compose.yaml            # base: images, networks, dependencies
compose.override.yaml   # auto-applied in dev (bind mounts, ports)
compose.prod.yaml       # production: limits, health checks, secrets

# Deploy to production by combining base + prod override
docker compose -f compose.yaml -f compose.prod.yaml up -d

Profiles

Profiles let optional services stay dormant until you ask for them — perfect for a monitoring or logging stack you don't always need running.

services:
  api:
    image: ${REGISTRY}/backend:${TAG}
    # no profile → always starts

  prometheus:
    image: prom/prometheus:latest
    profiles: [monitoring]     # only starts when requested

  grafana:
    image: grafana/grafana:latest
    profiles: [monitoring]

# Core app only
docker compose up -d

# Add the monitoring stack
docker compose --profile monitoring up -d

Production-Critical Features

Health checks and dependency ordering

Health checks let the API wait for a genuinely-ready database rather than a merely-started one:

services:
  api:
    depends_on:
      db:
        condition: service_healthy   # wait until db passes its health check

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      interval: 10s
      timeout: 5s
      retries: 5

Restart policies

services:
  worker:
    deploy:
      restart_policy:
        condition: on-failure   # any | on-failure | none
        delay: 5s
        max_attempts: 3
        window: 120s

Secrets, not environment passwords

Passwords in environment: leak into docker inspect and logs. Compose secrets are mounted as files under /run/secrets/ and kept out of the image and process environment.

services:
  api:
    environment:
      - DB_USER=appuser
      - DB_PASSWORD_FILE=/run/secrets/db_password  # app reads the file
    secrets: [db_password]

secrets:
  db_password:
    file: ./secrets/db_password.txt

Network segmentation

Put the database on an internal network so it's reachable by the API but has no route to the internet. The web tier sits on a public-facing network; the API bridges both.

networks:
  frontend:            # public-facing
  backend:
    internal: true     # no external route — DB is hidden

Scaling & High Availability

A single Compose host can't survive a machine failure. Docker Swarm turns the same Compose file into a multi-node cluster with built-in load balancing, service discovery, and rolling updates — no new file format to learn.

# Turn the current machine into a Swarm manager
docker swarm init

# Deploy the stack across the cluster
docker stack deploy -c compose.yaml -c compose.prod.yaml myapp

# Scale a service to five replicas
docker service scale myapp_web=5

Zero-downtime rolling updates

Update replicas a few at a time, and automatically roll back if the new version fails its health check:

services:
  web:
    image: ${REGISTRY}/frontend:${TAG}
    deploy:
      replicas: 4
      update_config:
        parallelism: 1        # one at a time
        delay: 10s
        order: start-first    # start new before stopping old
        failure_action: rollback
        monitor: 60s

Beyond Compose

Compose (with Swarm) covers a lot of ground, but at large scale — complex microservices, multi-region, advanced autoscaling — teams often graduate to Kubernetes. Choose based on your actual needs, not hype.

Hands-on Exercise

# compose.yaml (development)
services:
  web:
    build: ./frontend
    ports: ["3000:3000"]
    volumes:
      - ./frontend:/app
    environment:
      - NODE_ENV=development
    command: npm start

  api:
    build: ./backend
    ports: ["4000:4000"]
    environment:
      - NODE_ENV=development
      - DATABASE_URL=mongodb://db:27017/devdb
    depends_on: [db]

  db:
    image: mongo:7
    ports: ["27017:27017"]
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

# compose.prod.yaml (production)
services:
  web:
    image: ${REGISTRY}/frontend:${TAG}
    deploy:
      replicas: 2
      resources:
        limits: { cpus: '0.5', memory: 512M }
        reservations: { cpus: '0.1', memory: 128M }
      restart_policy: { condition: on-failure, max_attempts: 3 }
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    networks: [frontend]
    ports: ["80:3000"]
    environment:
      - NODE_ENV=production
      - REACT_APP_API_URL=http://api:4000

  api:
    image: ${REGISTRY}/backend:${TAG}
    deploy:
      resources:
        limits: { cpus: '1.0', memory: 1G }
      restart_policy: { condition: any }
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:4000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    networks: [frontend, backend]
    environment:
      - NODE_ENV=production
      - DATABASE_URL=mongodb://db:27017/proddb
      - DATABASE_PASSWORD_FILE=/run/secrets/db_password
    depends_on:
      db: { condition: service_healthy }
    secrets: [db_password]

  db:
    image: mongo:7
    deploy:
      resources:
        limits: { cpus: '2.0', memory: 2G }
      restart_policy: { condition: any }
    healthcheck:
      test: ["CMD-SHELL", "mongosh --quiet --eval \"db.adminCommand('ping')\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 40s
    volumes:
      - mongodb_data:/data/db
    networks: [backend]
    environment:
      - MONGO_INITDB_ROOT_USERNAME=appuser
      - MONGO_INITDB_ROOT_PASSWORD_FILE=/run/secrets/db_password
    secrets: [db_password]

networks:
  frontend:
  backend:
    internal: true

volumes:
  mongodb_data:

secrets:
  db_password:
    file: ./secrets/db_password.txt

#!/usr/bin/env bash
set -euo pipefail

export REGISTRY="registry.example.com"
export TAG="$(git describe --tags --always)"

mkdir -p secrets
[ -f secrets/db_password.txt ] || openssl rand -base64 24 > secrets/db_password.txt

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose ps

Best Practices

Summary & Quiz

📚 Further Reading

• Docker — Compose in Production
• Compose File Reference
• Docker Swarm Documentation

🚀 What's Next?

You can now build, optimize, and orchestrate containers. Next we zoom out to the platforms that host them: a comparison of the major cloud service providers.