Docker Compose for Production: The Hard Truths They Don't Tell You

You've been using Docker Compose for local dev. It's great. Now your boss says 'ship it to production with compose.' That's where the pain starts. I've seen a simple compose file bring down a payments service because someone forgot to set a memory limit — the container ate all the RAM, the kernel OOM-killed the database, and the entire platform went dark at 3 AM. Docker Compose for production is not docker-compose up -d. It's a completely different beast. By the end of this, you'll know exactly what to add, what to remove, and what to watch for when running compose in production. You'll be able to write a compose file that survives a traffic spike, a node failure, and a junior dev's 'quick fix'.

Why Your Dev Compose File Will Burn Production

The compose file you use for local development is optimized for convenience, not reliability. It probably has ports exposed to the world, no resource limits, and a restart policy of 'no'. In production, that's a disaster. I've seen a dev compose file with depends_on: - db and no health check — the app started before the database was ready, failed, and the restart policy wasn't set, so it stayed dead. The classic rookie mistake here costs you a full table lock on writes because the app connects before the DB is accepting queries. You need health checks, condition: service_healthy on depends_on, and proper restart policies. Don't assume order — enforce it.

// io.thecodeforge — DevOps tutorial

version: '3.8'

services:
  api:
    image: myapp/api:latest
    ports:
      - "127.0.0.1:8080:8080"  # Bind to localhost only — never 0.0.0.0 in production
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s  # Give app time to initialize
    depends_on:
      db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  db:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 1G

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

volumes:
  pgdata:

Resource Limits: The One Thing Everyone Forgets

Without resource limits, a single container can consume all host memory and get OOM-killed, taking down other services. Worse, a CPU-hungry container can starve the rest. I've seen a log aggregator with a memory leak eat 8GB before the kernel killed it — and the database was on the same host. The fix: always set deploy.resources.limits.memory and deploy.resources.limits.cpus. Use reservations to guarantee minimum resources. For memory, also set --memory-swap to allow controlled swap usage. The rule of thumb: limit memory to 80% of what you expect the container to need under peak load. Monitor with docker stats and adjust.

// io.thecodeforge — DevOps tutorial

services:
  worker:
    image: myapp/worker:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'        # One full core
          memory: 512M        # Hard limit
        reservations:
          cpus: '0.5'         # Guaranteed minimum
          memory: 256M
    # Optional: allow swap up to 1GB total (memory + swap)
    # memswap_limit: 1G
    # mem_swappiness: 0  # Disable swapping if possible

Health Checks: The Difference Between Self-Healing and Self-Destructing

A container is 'running' if its main process is alive. That doesn't mean your app is healthy. I've seen a Node.js app that was running but stuck in an infinite loop — the health endpoint never responded, but Docker thought it was fine. The load balancer kept sending traffic, users got timeouts, and the monitoring didn't catch it because the container was 'up'. Health checks fix this. They tell Docker (and orchestrators) when a container is truly ready. Use them in depends_on with condition: service_healthy to ensure startup order. Also use them in restart policies — if health check fails, Docker can restart the container. The key is setting a proper start_period: give your app time to initialize before health checks start.

// io.thecodeforge — DevOps tutorial

services:
  web:
    image: myapp/web:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s  # App may take 60s to start
    restart: unless-stopped
    # If health check fails 3 times, container is marked unhealthy
    # Docker will restart it (unless-stopped policy)
    # But only if the main process exits — health check alone doesn't trigger restart
    # For auto-restart on unhealthy, use a process manager or orchestration

Logging: Don't Let Logs Fill Your Disk

Default Docker logging uses json-file driver with no rotation. In production, a chatty app can fill a disk in hours. I've seen a misconfigured logger write 50GB of logs in a day, causing the host to run out of space, which killed all containers. The fix: configure logging driver with max-size and max-file. Better yet, use a centralized logging system (ELK, Loki, Datadog) with the syslog or fluentd driver. But even with centralized logging, always set local rotation as a safety net. Also consider log levels — in production, set to warn or error unless debugging.

// io.thecodeforge — DevOps tutorial

services:
  app:
    image: myapp/app:latest
    logging:
      driver: "json-file"
      options:
        max-size: "10m"   # Rotate when log file reaches 10MB
        max-file: "3"      # Keep 3 rotated files (30MB total)
        # Alternative: use syslog to send to central server
        # driver: "syslog"
        # options:
        #   syslog-address: "tcp://logs.example.com:514"
        #   tag: "{{.Name}}/{{.ID}}"

Secrets and Configs: Never Hardcode in Production

In dev, you might set environment variables directly in compose. In production, that's a security risk. Anyone with access to the compose file or the host can see secrets. Use Docker secrets (swarm mode) or bind-mount secret files. For compose without swarm, use the secrets: directive with file: or external: true. Never use environment: for passwords, API keys, or tokens. Also, use configs for non-sensitive configuration files. The pattern: write secrets to files outside the compose directory, set permissions to 600, and mount them. The app reads them at startup.

// io.thecodeforge — DevOps tutorial

services:
  api:
    image: myapp/api:latest
    secrets:
      - db_password
      - api_key
    configs:
      - source: app_config
        target: /etc/app/config.yml

secrets:
  db_password:
    file: ./secrets/db_password.txt  # Permissions 600
  api_key:
    external: true  # Created outside compose: docker secret create api_key -

configs:
  app_config:
    file: ./config/production.yml

Networking: Isolation and Service Discovery

In production, you don't want all containers on the same network. Isolate tiers: a frontend network, a backend network, and a database network. Only expose necessary ports. Use internal networks for databases. Docker Compose creates a default network, but you should define custom networks with driver: overlay for multi-host (swarm) or bridge for single host. Also, use container_name for stable DNS resolution. I've seen a service discovery fail because the container name changed after a restart — use container_name or service name (which is stable).

// io.thecodeforge — DevOps tutorial

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # No external access
  database:
    driver: bridge
    internal: true

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    networks:
      - frontend
      - backend

  api:
    image: myapp/api:latest
    networks:
      - backend
      - database
    # No frontend network — API not directly exposed

  db:
    image: postgres:15
    networks:
      - database
    # Only accessible from backend network

Volumes: Persistent Data and Performance

In production, database data must survive container restarts. Use named volumes, not bind mounts, for database data. Bind mounts are fine for configs but not for data — they have permission issues and are harder to back up. For performance, consider volume drivers like local (default) or use a network filesystem (NFS, EFS) for multi-host setups. Also, set volume labels for backup automation. I've seen a production database lose data because someone used a bind mount and the host directory got deleted. Named volumes are managed by Docker and safer.

// io.thecodeforge — DevOps tutorial

services:
  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro  # Bind mount for init script
    # Named volume for data

volumes:
  pgdata:
    # Use a driver for backups or replication
    # driver: local
    # driver_opts:
    #   type: none
    #   device: /path/to/backup
    #   o: bind

When Not to Use Docker Compose in Production

Docker Compose is great for single-host deployments or small clusters. But if you need multi-host orchestration, rolling updates, auto-scaling, or service discovery across nodes, you need Kubernetes, Docker Swarm, or Nomad. Compose doesn't handle node failures — if the host goes down, everything goes down. Also, Compose doesn't have built-in secrets management (without swarm), and its health check auto-recovery is limited. Use Compose when: you have a single server, you need simplicity, and you can tolerate downtime during updates. Use Kubernetes when: you need high availability, scaling, or multi-host deployments. The rule of thumb: if you have more than 3 services or need zero-downtime deploys, move to an orchestrator.

// io.thecodeforge — DevOps tutorial

# Signs you should NOT use Docker Compose in production:
# 1. You need rolling updates without downtime
# 2. You have multiple hosts and need service discovery
# 3. You need auto-scaling based on load
# 4. You need secrets management without swarm mode
# 5. You can't tolerate a single host failure
# 6. You need per-container resource metrics and alerts

# In these cases, use Kubernetes, Docker Swarm, or Nomad.

Rolling Updates with Compose? Not Really — But Here's the Hack

Docker Compose doesn't support rolling updates natively. docker-compose up -d recreates all containers at once, causing downtime. The hack: use docker-compose scale to run multiple replicas, then update one by one. But this is fragile. Better: use Docker Swarm with docker stack deploy, which supports rolling updates. Or use a reverse proxy (nginx, HAProxy) with blue-green deployment: start new containers on different ports, then switch traffic. I've used a simple script that updates containers in sequence with health checks between each. It's not perfect, but it works for low-traffic services.

// io.thecodeforge — DevOps tutorial

#!/bin/bash
# Simple rolling update for a service with 3 replicas

SERVICE="api"
REPLICAS=3

for i in $(seq 1 $REPLICAS); do
  echo "Updating replica $i..."
  docker-compose up -d --no-deps --scale $SERVICE=$((REPLICAS - i + 1)) --no-recreate $SERVICE
  # Wait for health check
  sleep 30
  # Check health
  if ! docker-compose ps | grep "$SERVICE.*Up"; then
    echo "Replica $i failed, rolling back..."
    docker-compose up -d --no-deps --scale $SERVICE=$REPLICAS
    exit 1
  fi
done

echo "All replicas updated successfully."

Multi-Stage Builds with Compose — Smaller Images, Faster Deploys

Multi-stage builds let you use one Dockerfile with multiple FROM statements, each representing a build stage. In Compose, you reference a specific build target with the build.target key. The typical pattern: a builder stage installs all dev dependencies and compiles artifacts, then a runtime stage copies only the compiled output into a minimal base image. This produces production images that are 5-20x smaller than single-stage builds. In docker-compose.yml, set build.target: production to build only the runtime stage. The builder stage is never saved to the registry — it exists only during the build. Use this pattern to keep production images free of compilers, package managers, and dev dependencies, reducing the attack surface and deployment time. Compose resolves the target within the Dockerfile's multi-stage structure, so you can define different targets for development (with hot-reload tooling) and production (minimal runtime).

# Dockerfile with multi-stage build

# Stage 1: Builder
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# Stage 2: Production runtime
FROM node:20-alpine AS production
WORKDIR /app
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

# Stage 3: Development (optional, with dev deps)
FROM node:20-alpine AS development
WORKDIR /app
RUN npm ci && npm install -g nodemon
COPY . .
USER node
CMD ["nodemon", "src/index.js"]

Image Pinning by Digest in Production — Preventing Tag Mutability Attacks

Tags are mutable — the same tag can point to different images over time. A docker-compose.yml with image: myapp/api:latest can pull a different image on every deploy, even if you think you're deploying the same version. Image digests (SHA256 hashes) are immutable: image@sha256:abc123 always refers to exactly the same image. In production, pin every image by digest to prevent tag mutability attacks, accidental overwrites, and cache poisoning. When you push to your registry, record the digest from the push output (or use docker images --digests). In docker-compose.yml, replace image: myapp/api:v1.2.3 with image: myapp/api@sha256:a1b2c3d4. This guarantees that every deployment of that compose file uses the exact same image content. For base images (postgres, redis), use a specific tag AND verify the digest from Docker Hub. Update pinned digests only when you explicitly intend to deploy a new version. The trade-off: you need a process to update digests in your compose files, usually via CI after a successful build and scan.

services:
  api:
    # Pinned by digest — this exact image, always
    image: ghcr.io/myorg/api@sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890
    restart: unless-stopped

  postgres:
    # Base image pinned to a specific tag (not latest)
    image: postgres:15-alpine
    # In production, also pin base images by digest:
    # image: postgres@sha256:official_postgres_15_alpine_digest
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

.dockerignore Best Practices — Shrinking Build Context, Speeding Builds

The .dockerignore file excludes files from the Docker build context, reducing the amount of data sent to the Docker daemon during docker compose build. A bloated build context (node_modules, .git, .env files) slows builds and can leak secrets. Every file in the build context is sent to the Docker daemon, even if the Dockerfile doesn't COPY it. A .git directory alone can be hundreds of megabytes. Critical exclusions: .env (contains secrets), .git (massive directory, not needed for build), node_modules (reinstalled inside the container), .pem, .key (private keys), __pycache__, .DS_Store, .vscode, .idea, *.log, .terraform, and any CI artifacts. The .dockerignore file follows the same glob patterns as .gitignore. Place it at the root of each build context directory. For monorepos, each service should have its own .dockerignore in its build context directory. A well-configured .dockerignore can reduce build context from 500MB to under 1MB, cutting build time by 80%.

# .dockerignore — always at the root of the build context

# Secrets
.env
*.pem
*.key
*.cert

# Version control
.git
.gitignore
.gitattributes

# Dependencies (reinstalled inside container)
node_modules
vendor
.python_packages

# IDE and editor files
.vscode
.idea
*.swp
*.swo
.DS_Store

# Logs
*.log
npm-debug.log*

# Build artifacts
dist
build
*.tsbuildinfo

# CI/CD
.ci
.github
.gitlab

# Terraform (if in same repo)
.terraform
terraform.tfstate*

# Docker
Dockerfile
docker-compose*.yml

Hadolint Dockerfile Linting in CI — Automated Quality Gates

Hadolint is a Dockerfile linter that checks for best practices, security issues, and common mistakes. It parses the Dockerfile and applies rules from the hadolint rule set (DL3000-DL3099). Run hadolint in CI as a required PR check to enforce Dockerfile quality before merging. Configure typical rules: DL3006 (always tag image versions, never use latest), DL3008 (pin apt-get package versions), DL3009 (delete apt-get lists), DL3018 (pin pip package versions), DL4006 (set SHELL for readability), and DL3045 (use COPY instead of ADD unless you need tar extraction). Hadolint integrates with pre-commit hooks, GitHub Actions, GitLab CI, and any CI system that runs shell commands. It also supports a .hadolint.yaml config file to customize rules, ignore specific violations, and set trusted registries for base image validation. In production CI pipelines, run hadolint before docker compose build to fail fast — if the Dockerfile fails linting, don't waste time building it.

# Install hadolint (CI runner setup)
# Linux x86_64:
curl -sL https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 -o /usr/local/bin/hadolint
chmod +x /usr/local/bin/hadolint

# macOS:
# brew install hadolint

# Lint all Dockerfiles in the project
hadolint ./**/Dockerfile

# With custom config file
hadolint -c .hadolint.yaml ./api/Dockerfile

# GitHub Actions step:
# - name: Lint Dockerfiles
#   run: hadolint ./**/Dockerfile

# Pre-commit setup (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/hadolint/hadolint
#     rev: v2.12.0
#     hooks:
#       - id: hadolint

Reverse Proxy Integration (Traefik/Caddy) in Production Compose

In production, you should never expose application containers directly to the internet. Use a reverse proxy service (Traefik or Caddy) as the sole ingress point. The proxy handles TLS termination, automatic certificate management, rate limiting, and routing to backend services. For Traefik, use Compose labels for dynamic configuration — Traefik reads service labels and automatically configures routing. For Caddy, use Caddyfile for static configuration. Both support automatic HTTPS via Let's Encrypt. The reverse proxy runs on port 80/443 and routes traffic based on hostname or path to internal services on their container ports. This pattern eliminates the need for each service to manage TLS certificates, and it centralizes access control, logging, and rate limiting. In the compose file, the proxy service is the only service with host port mappings. All backend services use expose: (no host port) and are only reachable through the proxy's internal network. For Traefik, labels on each service declare routing rules; for Caddy, a bind-mounted Caddyfile defines the reverse proxy configuration.

# Traefik integration pattern
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@example.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt
    labels:
      - "traefik.enable=true"

  api:
    image: myapp/api:latest
    expose:
      - "3000"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`api.example.com`)"
      - "traefik.http.routers.api.tls=true"
      - "traefik.http.routers.api.tls.certresolver=letsencrypt"
      - "traefik.http.services.api.loadbalancer.server.port=3000"

  frontend:
    image: myapp/frontend:latest
    expose:
      - "80"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.frontend.rule=Host(`example.com`)"
      - "traefik.http.routers.frontend.tls=true"
      - "traefik.http.routers.frontend.tls.certresolver=letsencrypt"

volumes:
  letsencrypt: