On this page

Docker Compose Advanced Cheat Sheet

Docker Compose defines and runs multi-container applications. This cheat sheet covers the Compose Specification and the docker compose CLI plugin (v2 and later; v5 is current). The legacy Python docker-compose v1 binary is end-of-life, and the top-level version: key is obsolete: Compose ignores it and prints a warning, so leave it out. It goes beyond the basics into health checks, profiles, override files, networking, secrets, and patterns for both development and production.

Related: Docker Cheat Sheet | Supply Chain Security | Observability Tools


CLI Quick Reference

CommandDescription
docker compose upCreate and start all services
docker compose up -dStart in detached (background) mode
docker compose up --buildRebuild images before starting
docker compose up --force-recreateRecreate containers even if config unchanged
docker compose up service1 service2Start specific services (+ dependencies)
docker compose downStop and remove containers, networks
docker compose down -vAlso remove named volumes
docker compose down --rmi allAlso remove images
docker compose psList running containers
docker compose ps -aList all containers (including stopped)
docker compose logsView logs from all services
docker compose logs -f apiFollow logs for specific service
docker compose logs --tail 50 apiLast 50 lines from service
docker compose exec api shShell into running service
docker compose run api npm testRun one-off command in new container
docker compose buildBuild or rebuild all images
docker compose pullPull latest images
docker compose restart apiRestart a service
docker compose stopStop services without removing
docker compose configValidate and view resolved config
docker compose topDisplay running processes
docker compose watchWatch for file changes and sync/rebuild
docker compose up -d --waitStart and block until services are running/healthy (good for CI)
docker compose up --no-deps apiStart a service without its dependencies
docker compose up -d --force-recreate --no-deps apiRecreate just one service
docker compose up --abort-on-container-exit --exit-code-from testsRun a test stack, exit with the tests' code
docker compose up -d --scale worker=3Run 3 replicas of a service
docker compose run --rm api npm testOne-off command, remove container afterwards
docker compose run --rm --service-ports apiOne-off run with the service's ports published
docker compose exec -T db psql -U userExec without a TTY (scripts, CI, piping)
docker compose cp api:/app/log.txt .Copy files from/to a service container
docker compose rm -sf apiStop and remove one service's container
docker compose lsList Compose projects on this host
docker compose imagesImages used by the project's containers
docker compose port api 3000Which host port maps to container port 3000
docker compose config --servicesList service names
docker compose versionShow the Compose version

Global Flags (go before the subcommand)

FlagDescription
-f compose.yaml -f compose.prod.yamlUse these files, merged left to right
-p myprojProject name (default: directory name)
--profile debugEnable a profile, e.g. docker compose --profile debug up
--env-file .env.prodUse a different file for variable interpolation
--project-directory ./appBase directory for relative paths

Environment equivalents: COMPOSE_FILE, COMPOSE_PROJECT_NAME, COMPOSE_PROFILES.


Service Definition

Complete Service Example

# compose.yaml (or docker-compose.yml)
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: development          # Multi-stage build target
      args:
        NODE_VERSION: "22"
    image: myapp-api:dev
    container_name: myapp-api
    restart: unless-stopped
    ports:
      - "3000:3000"                # host:container
      - "9229:9229"                # Node.js debugger
    volumes:
      - ./src:/app/src             # Bind mount for hot reload
      - /app/node_modules          # Anonymous volume (preserve node_modules)
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://user:pass@db:5432/myapp
      REDIS_URL: redis://cache:6379
    env_file:
      - .env
      - .env.local                 # Overrides .env
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks:
      - backend
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Health Checks

Health checks tell Compose when a service is actually ready, not just when the container starts.

services:
  # PostgreSQL — wait for it to accept connections
  db:
    image: postgres:18-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER -d $POSTGRES_DB"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

  # Redis — wait for PING response
  cache:
    image: redis:8-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3

  # MySQL — wait for mysqladmin
  mysql:
    image: mysql:8.4
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 30s

  # Elasticsearch — wait for cluster health
  elasticsearch:
    image: elasticsearch:9.5.5
    environment:
      discovery.type: single-node
      xpack.security.enabled: "false"   # local dev only; security is on by default and the plain-HTTP check would fail
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health | grep -q '\"status\":\"green\"\\|\"status\":\"yellow\"'"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 60s

  # Kafka — wait for broker to be ready
  kafka:
    image: confluentinc/cp-kafka:8.4.0
    healthcheck:
      test: ["CMD-SHELL", "kafka-broker-api-versions --bootstrap-server localhost:9092"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

  # HTTP service — custom health endpoint
  api:
    build: .
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s

TIP

Use start_period to give slow-starting services time to initialize before health checks begin failing. Without it, a database that takes 20 seconds to start will appear unhealthy and may be restarted prematurely.

Dependency Ordering with Health Checks

services:
  db:
    image: postgres:18-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 5s
      timeout: 3s
      retries: 5

  migrations:
    build: .
    command: npx prisma migrate deploy
    depends_on:
      db:
        condition: service_healthy    # Wait for DB to be healthy
    restart: "no"                     # Run once, do not restart

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy
      migrations:
        condition: service_completed_successfully  # Wait for migrations to finish
      cache:
        condition: service_started    # Just wait for container start

WARNING

depends_on without a condition only waits for the container to start, not for the service to be ready. A PostgreSQL container starts in ~1 second, but the database engine may take 5-10 seconds to accept connections. Always use condition: service_healthy for databases.

depends_on Options

KeyValuesEffect
conditionservice_started (default)Wait for the container to start
service_healthyWait for its healthcheck to pass
service_completed_successfullyWait for it to exit with code 0 (migrations, seeders)
restarttrueRestart this service when the dependency is restarted/updated by Compose
requiredfalseOnly warn (don't fail) if the dependency isn't running or isn't enabled by a profile
services:
  api:
    depends_on:
      db:
        condition: service_healthy
        restart: true
      telemetry:
        condition: service_started
        required: false

depends_on only orders startup within one docker compose up. It does not restart your app if the database dies later, so the app still needs retry logic.


Networking

services:
  # Frontend network — exposed to host
  web:
    build: ./frontend
    ports:
      - "8080:80"
    networks:
      - frontend

  # API — bridges both networks
  api:
    build: ./api
    ports:
      - "3000:3000"
    networks:
      - frontend        # Reachable from web
      - backend         # Can reach db

  # Database — only on backend network
  db:
    image: postgres:18-alpine
    networks:
      - backend          # NOT on frontend — web cannot reach db directly

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true       # No external access (no internet from db)
flowchart LR
    subgraph frontend["frontend network"]
        WEB["web:80"]
        API_F["api:3000"]
    end

    subgraph backend["backend network (internal)"]
        API_B["api:3000"]
        DB["db:5432"]
        CACHE["cache:6379"]
    end

    HOST[Host Machine] -->|":8080"| WEB
    HOST -->|":3000"| API_F
    WEB -->|"api:3000"| API_F
    API_B -->|"db:5432"| DB
    API_B -->|"cache:6379"| CACHE

    API_F -.- API_B

DNS Resolution

Inside a Compose network, services can reach each other by service name:

services:
  api:
    environment:
      # Use service names as hostnames
      DATABASE_URL: postgres://user:pass@db:5432/myapp     # "db" resolves to the db container
      REDIS_URL: redis://cache:6379                         # "cache" resolves to the cache container
      KAFKA_BROKERS: kafka:9092                             # "kafka" resolves to the kafka container

Ports & Host Access

services:
  api:
    ports:
      - "3000:3000"                 # all host interfaces
      - "127.0.0.1:5432:5432"       # localhost only
      - "8000-8010:8000-8010"       # range
    expose:
      - "9090"                      # container-to-container only (documentation)
    extra_hosts:
      - "host.docker.internal:host-gateway"   # reach services on the host (needed on Linux)

Inside the network, use the container port (db:5432), not the host port. The default network is <project>_default; use networks: { default: { name: shared, external: true } } to join a network created outside Compose.


Profiles

Profiles let you define optional services that only start when explicitly requested.

services:
  api:
    build: .
    # No profile — always starts

  db:
    image: postgres:18-alpine
    # No profile — always starts

  # Debug tools — only start with --profile debug
  pgadmin:
    image: dpage/pgadmin4
    ports:
      - "5050:80"
    profiles:
      - debug

  mailhog:
    image: mailhog/mailhog        # unmaintained; axllent/mailpit is the maintained drop-in (same 8025 UI, 1025 SMTP)
    ports:
      - "8025:8025"
    profiles:
      - debug

  # Monitoring — only start with --profile monitoring
  prometheus:
    image: prom/prometheus
    profiles:
      - monitoring

  grafana:
    image: grafana/grafana
    profiles:
      - monitoring

  # Testing — only start with --profile test
  test-runner:
    build:
      context: .
      target: test
    command: npm test
    profiles:
      - test
    depends_on:
      db:
        condition: service_healthy
# Start core services only (api + db)
docker compose up

# Start core + debug tools (--profile is a global flag: it goes BEFORE the subcommand)
docker compose --profile debug up

# Start core + monitoring
docker compose --profile monitoring up

# Start multiple profiles
docker compose --profile debug --profile monitoring up
COMPOSE_PROFILES=debug,monitoring docker compose up   # same, via env var

# Start every profile
docker compose --profile "*" up

# Run tests: naming a profiled service enables its profile automatically
docker compose run --rm test-runner

# Stop everything, including profiled services
docker compose --profile "*" down

Services without profiles always start. A service that is enabled must not depends_on a service whose profile is disabled (unless required: false).


Override Files

Compose automatically merges multiple files. Use overrides to customize for different environments.

project/
  compose.yaml              # Base configuration
  compose.override.yaml     # Dev overrides (auto-loaded)
  compose.prod.yaml         # Production overrides
  compose.test.yaml         # Test overrides

Base (compose.yaml)

services:
  api:
    image: myapp-api:latest
    environment:
      NODE_ENV: production
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  pgdata:

Development Override (compose.override.yaml)

# Automatically merged when running `docker compose up`
services:
  api:
    build:
      context: .
      target: development
    environment:
      NODE_ENV: development
    ports:
      - "3000:3000"
      - "9229:9229"
    volumes:
      - ./src:/app/src
    command: npm run dev

  db:
    ports:
      - "5432:5432"       # Expose DB port for local tools
    environment:
      POSTGRES_PASSWORD: devpassword

Production Override (compose.prod.yaml)

services:
  api:
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: "2.0"
          memory: 1G
    environment:
      NODE_ENV: production
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"

  db:
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt
# Development (auto-loads compose.override.yaml)
docker compose up

# Production (skip override, use prod)
docker compose -f compose.yaml -f compose.prod.yaml up -d

# Testing
docker compose -f compose.yaml -f compose.test.yaml run test-runner

# See what the merge produced
docker compose -f compose.yaml -f compose.prod.yaml config

Merge Rules

Field typeMerge behaviour
Single values (image, command, restart)Later file wins
Maps (environment, labels, deploy)Merged key by key
ports, expose, dnsConcatenated (you cannot remove a port in an override)
volumes, devicesMerged by container path
Remove/replace a valueports: !reset [] clears it, command: !override [...] replaces it

include, extends and Anchors

# Pull in another project's compose file (paths resolve relative to that file)
include:
  - ../shared/observability.compose.yaml

# Reusable fragment: top-level keys starting with x- are ignored by Compose
x-common-env: &common-env
  LOG_LEVEL: info
  TZ: UTC

services:
  api:
    environment:
      <<: *common-env
      PORT: "3000"

  worker:
    extends:
      file: common.yaml     # or omit `file` to extend a service in this file
      service: base-node

Variable Interpolation

Compose substitutes variables from the shell and from .env in the project directory (not from env_file:, which only sets variables inside the container).

SyntaxMeaning
${VAR}Value of VAR (empty if unset, with a warning)
${VAR:-default}default if VAR is unset or empty
${VAR-default}default only if VAR is unset
${VAR:?error msg}Fail if VAR is unset or empty
${VAR:+other}other if VAR is set and non-empty
$$Literal $ (e.g. in a command: that uses shell variables)
services:
  api:
    image: "registry.example.com/api:${TAG:-latest}"
    env_file:
      - path: .env.local
        required: false     # don't fail if the file is missing

Precedence inside the container (highest first): docker compose run -e, environment:, env_file:, the image's ENV.


Secrets

services:
  api:
    build: .
    secrets:
      - db_password
      - api_key
    environment:
      # Read from file mounted at /run/secrets/
      DB_PASSWORD_FILE: /run/secrets/db_password

  db:
    image: postgres:18-alpine
    secrets:
      - db_password
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

# Define secrets
secrets:
  db_password:
    file: ./secrets/db_password.txt    # From file
  api_key:
    environment: "API_KEY"              # From host environment variable

DANGER

Never put passwords directly in environment: in your compose file — the file is committed to version control. Use secrets: with file references, or env_file: pointing to a .gitignored file. For production, use external secret managers (Vault, AWS Secrets Manager).


Volumes

services:
  api:
    volumes:
      # Bind mount — sync host files into container (development)
      - ./src:/app/src:ro            # Read-only bind mount
      - ./config:/app/config         # Read-write bind mount

      # Named volume — persists across container restarts
      - node_modules:/app/node_modules

      # Anonymous volume — not shared; left dangling by `docker compose down`, deleted by `down -v`
      - /app/tmp

  db:
    volumes:
      - pgdata:/var/lib/postgresql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro

volumes:
  pgdata:
    driver: local
  node_modules:
    driver: local

Volume Tips

PatternUse Case
./src:/app/srcHot reload in development
./src:/app/src:roPrevent container from modifying source
/app/node_modulesPreserve node_modules inside container
Named volume (pgdata:)Persist database data across restarts
driver: localDefault, stored on host filesystem
external: trueUse a volume created outside Compose (never deleted by down -v)
tmpfs: /tmpIn-memory scratch dir

Named volumes are prefixed with the project name (myapp_pgdata). Set name: pgdata on the volume to pin the real name.


Watch Mode (Compose Watch)

Compose Watch syncs file changes without rebuilding the entire container:

services:
  api:
    build: .
    develop:
      watch:
        # Sync source files — trigger hot reload
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
            - "*.test.ts"

        # Rebuild on dependency changes
        - action: rebuild
          path: ./package.json

        # Sync + restart on config changes
        - action: sync+restart
          path: ./config
          target: /app/config
# Start with watch mode
docker compose watch

# Or combine with up
docker compose up --watch
ActionWhat happens on change
syncCopy changed files into the container (app must hot-reload)
sync+restartCopy, then restart the container
sync+execCopy, then run exec.command in the container
restartRestart the container, no copy
rebuildRebuild the image and recreate the container

Watch requires a build: section, and sync needs the container to have permission to write target. .dockerignore rules apply to watched paths.

Other Useful Service Keys

KeyExamplePurpose
initinit: trueRun an init as PID 1 for signal forwarding
stop_grace_periodstop_grace_period: 30sTime between SIGTERM and SIGKILL (default 10s)
pull_policypull_policy: alwaysalways, missing (default), never, build
platformplatform: linux/amd64Force an architecture
useruser: "1000:1000"Run as a specific UID:GID
working_dirworking_dir: /appOverride WORKDIR
entrypoint / commandcommand: ["npm", "run", "dev"]Override image ENTRYPOINT / CMD
tty / stdin_opentty: trueSame as docker run -t / -i
labelslabels: [traefik.enable=true]Container labels (reverse proxies, tooling)
configsconfigs: [nginx_conf]Mount a config file like a secret, for non-sensitive data

Full-Stack Development Example

# compose.yaml — Full-stack app with all patterns
services:
  # === Frontend ===
  web:
    build:
      context: ./frontend
      target: development
    ports:
      - "5173:5173"
    volumes:
      - ./frontend/src:/app/src
    environment:
      VITE_API_URL: http://localhost:3000
    networks:
      - frontend

  # === API ===
  api:
    build:
      context: ./api
      target: development
    ports:
      - "3000:3000"
    volumes:
      - ./api/src:/app/src
    environment:
      DATABASE_URL: postgres://myapp:secret@db:5432/myapp
      REDIS_URL: redis://cache:6379
      JWT_SECRET_FILE: /run/secrets/jwt_secret
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    secrets:
      - jwt_secret
    networks:
      - frontend
      - backend
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 10s

  # === Database ===
  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql
      - ./db/init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp"]
      interval: 5s
      timeout: 3s
      retries: 5

  # === Cache ===
  cache:
    image: redis:8-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    networks:
      - backend
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3

  # === Worker (background jobs) ===
  worker:
    build:
      context: ./api
      target: development
    command: npm run worker
    volumes:
      - ./api/src:/app/src
    environment:
      DATABASE_URL: postgres://myapp:secret@db:5432/myapp
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    networks:
      - backend

  # === Debug Tools (profile: debug) ===
  pgadmin:
    image: dpage/pgadmin4
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@local.dev
      PGADMIN_DEFAULT_PASSWORD: admin
    profiles:
      - debug
    networks:
      - backend

  redis-commander:
    image: rediscommander/redis-commander
    ports:
      - "8081:8081"
    environment:
      REDIS_HOSTS: local:cache:6379
    profiles:
      - debug
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

volumes:
  pgdata:
  redis_data:

secrets:
  jwt_secret:
    file: ./secrets/jwt_secret.txt
# Daily development
docker compose up

# With debug tools (pgAdmin, Redis Commander)
docker compose --profile debug up

# Rebuild after Dockerfile changes
docker compose up --build

# Reset everything (volumes, images, containers)
docker compose down -v --rmi local

Common Gotchas

WARNING

Port conflicts: If docker compose up fails with "port already in use", check for other containers or local services. Use lsof -i :3000 (Linux/Mac) or netstat -ano | findstr :3000 (Windows) to find the process.

TIP

Orphan containers: If you rename or remove a service from your compose file, the old container persists. Use docker compose up --remove-orphans to clean them up.

DANGER

Volume data loss: docker compose down -v deletes all named volumes, including your database data. Use docker compose down (without -v) to keep data between restarts. Only use -v when you intentionally want a fresh start.


Further Reading


Test Yourself
  1. What command rebuilds images and starts all services? docker compose up --build

  2. How do you start the core services plus those tagged with the debug profile? docker compose --profile debug up

  3. What depends_on condition waits for a health check to pass before starting a dependent service? condition: service_healthy

  4. What file is automatically merged with compose.yaml when running docker compose up? compose.override.yaml

  5. How do you make a network internal-only (no internet access)? Set internal: true on the network definition.

  6. What Compose Watch action rebuilds the container when a file changes? action: rebuild

  7. How do you run a one-off command in a new container without starting all services? docker compose run service-name command

  8. What flag also removes named volumes when tearing down? docker compose down -v

  9. How do you validate and view the fully resolved Compose configuration? docker compose config

  10. Where are Docker Compose secrets mounted inside the container? /run/secrets/secret-name

Common Gotchas

  • docker compose down -v deletes your database data. Named volumes containing PostgreSQL, MySQL, or Redis data are permanently deleted. Only use -v when you want a fresh start.
  • depends_on without condition only waits for container start, not readiness. A PostgreSQL container starts in ~1 second, but the database engine takes 5-10 seconds to accept connections. Always use condition: service_healthy for databases.
  • Putting passwords in environment: in compose files. The compose file is committed to version control. Use secrets:, env_file: with a .gitignored file, or external secret managers.
  • Orphan containers from renamed services. If you rename or remove a service, the old container stays. Use docker compose up --remove-orphans to clean up.
  • --profile after the subcommand fails. docker compose up --profile debug errors with unknown flag; write docker compose --profile debug up.
  • version: at the top of the file is obsolete. Compose ignores it and warns. Delete it.
  • docker-compose (with a hyphen) is the dead v1 binary. Use docker compose. Some distros ship a docker-compose shim that forwards to v2; scripts should still use the plugin form.
  • .env vs env_file:. .env feeds ${VAR} substitution in the YAML; env_file: sets variables inside the container. They are unrelated.
  • container_name blocks scaling. Two replicas cannot share a name, so --scale and deploy.replicas fail.
  • Editing compose.yaml does not change running containers. Run docker compose up -d again; Compose recreates only the services whose config changed.
  • Unquoted port mappings like 22:22 can be parsed by YAML 1.1 tools as base-60 numbers. Always quote ports.
  • postgres 18+ images moved the data directory. Mount the volume at /var/lib/postgresql (not /var/lib/postgresql/data), or the container refuses to start with an old-style mount.

One-Liner Summary

Docker Compose defines multi-container applications in a single YAML file -- master health checks, profiles, override files, and secrets to create reproducible development environments that mirror production.