Docker Compose Cheatsheet

Top-Level Keys

Every docker-compose.yml file is built from these root-level keys. The services key is the only one that is required.

Service Configuration

Keys available inside each service definition. These control how the container is built, configured, and connected.

Healthcheck

Health checks let Compose wait until a service is actually ready before starting dependent services. Combine with depends_on: condition: service_healthy.

Volumes

Named volumes declared under the top-level volumes:key persist data beyond the container lifecycle. Bind mounts (host paths) are specified directly in the service's volumes: list.

Networks

By default Compose creates a single network for your project. Custom networks let you isolate services and control which containers can talk to each other.

Deploy & Resources

The deploy key controls replica count, resource limits, rolling update strategy, and placement. Originally Swarm-only, many fields are now respected by docker compose up in Compose V2.

CLI Commands

All docker compose (V2) commands. The legacy docker-compose (hyphenated) syntax works the same way.

Example Compose Files

Copy these production-ready examples and adapt them to your project. Each demonstrates common patterns: health checks, named volumes, multi-network isolation, and resource limits.

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/myapp
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_URL: http://localhost:4000
    depends_on:
      - api

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    ports:
      - "4000:4000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/myapp
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/certs:/etc/nginx/certs:ro
    depends_on:
      - app1
      - app2
    networks:
      - frontend

  app1:
    build: ./services/app1
    expose:
      - "8001"
    environment:
      - APP_NAME=service-one
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: "0.5"
          memory: 256M
    networks:
      - frontend
      - backend

  app2:
    build: ./services/app2
    expose:
      - "8002"
    environment:
      - APP_NAME=service-two
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: "0.5"
          memory: 256M
    networks:
      - frontend
      - backend

  worker:
    build: ./services/worker
    environment:
      RABBITMQ_URL: amqp://rabbit:5672
    depends_on:
      rabbit:
        condition: service_healthy
    deploy:
      replicas: 3
    networks:
      - backend

  rabbit:
    image: rabbitmq:3-management-alpine
    ports:
      - "15672:15672"
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_running"]
      interval: 30s
      timeout: 10s
      retries: 5
    networks:
      - backend

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: multi
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

networks:
  frontend:
  backend:

volumes:
  pgdata:

# docker-compose.override.yml — auto-merged with docker-compose.yml
services:
  web:
    build:
      context: .
      target: development
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      NODE_ENV: development
      DEBUG: "true"
    ports:
      - "9229:9229"   # Node.js debugger
    command: npm run dev

  db:
    ports:
      - "5432:5432"   # Expose DB to host for local tools

Tips & Best Practices