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
| Command | Description |
|---|---|
docker compose up | Create and start all services |
docker compose up -d | Start in detached (background) mode |
docker compose up --build | Rebuild images before starting |
docker compose up --force-recreate | Recreate containers even if config unchanged |
docker compose up service1 service2 | Start specific services (+ dependencies) |
docker compose down | Stop and remove containers, networks |
docker compose down -v | Also remove named volumes |
docker compose down --rmi all | Also remove images |
docker compose ps | List running containers |
docker compose ps -a | List all containers (including stopped) |
docker compose logs | View logs from all services |
docker compose logs -f api | Follow logs for specific service |
docker compose logs --tail 50 api | Last 50 lines from service |
docker compose exec api sh | Shell into running service |
docker compose run api npm test | Run one-off command in new container |
docker compose build | Build or rebuild all images |
docker compose pull | Pull latest images |
docker compose restart api | Restart a service |
docker compose stop | Stop services without removing |
docker compose config | Validate and view resolved config |
docker compose top | Display running processes |
docker compose watch | Watch for file changes and sync/rebuild |
docker compose up -d --wait | Start and block until services are running/healthy (good for CI) |
docker compose up --no-deps api | Start a service without its dependencies |
docker compose up -d --force-recreate --no-deps api | Recreate just one service |
docker compose up --abort-on-container-exit --exit-code-from tests | Run a test stack, exit with the tests' code |
docker compose up -d --scale worker=3 | Run 3 replicas of a service |
docker compose run --rm api npm test | One-off command, remove container afterwards |
docker compose run --rm --service-ports api | One-off run with the service's ports published |
docker compose exec -T db psql -U user | Exec without a TTY (scripts, CI, piping) |
docker compose cp api:/app/log.txt . | Copy files from/to a service container |
docker compose rm -sf api | Stop and remove one service's container |
docker compose ls | List Compose projects on this host |
docker compose images | Images used by the project's containers |
docker compose port api 3000 | Which host port maps to container port 3000 |
docker compose config --services | List service names |
docker compose version | Show the Compose version |
Global Flags (go before the subcommand)
| Flag | Description |
|---|---|
-f compose.yaml -f compose.prod.yaml | Use these files, merged left to right |
-p myproj | Project name (default: directory name) |
--profile debug | Enable a profile, e.g. docker compose --profile debug up |
--env-file .env.prod | Use a different file for variable interpolation |
--project-directory ./app | Base 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
| Key | Values | Effect |
|---|---|---|
condition | service_started (default) | Wait for the container to start |
service_healthy | Wait for its healthcheck to pass | |
service_completed_successfully | Wait for it to exit with code 0 (migrations, seeders) | |
restart | true | Restart this service when the dependency is restarted/updated by Compose |
required | false | Only 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 type | Merge behaviour |
|---|---|
Single values (image, command, restart) | Later file wins |
Maps (environment, labels, deploy) | Merged key by key |
ports, expose, dns | Concatenated (you cannot remove a port in an override) |
volumes, devices | Merged by container path |
| Remove/replace a value | ports: !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).
| Syntax | Meaning |
|---|---|
${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
| Pattern | Use Case |
|---|---|
./src:/app/src | Hot reload in development |
./src:/app/src:ro | Prevent container from modifying source |
/app/node_modules | Preserve node_modules inside container |
Named volume (pgdata:) | Persist database data across restarts |
driver: local | Default, stored on host filesystem |
external: true | Use a volume created outside Compose (never deleted by down -v) |
tmpfs: /tmp | In-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
| Action | What happens on change |
|---|---|
sync | Copy changed files into the container (app must hot-reload) |
sync+restart | Copy, then restart the container |
sync+exec | Copy, then run exec.command in the container |
restart | Restart the container, no copy |
rebuild | Rebuild 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
| Key | Example | Purpose |
|---|---|---|
init | init: true | Run an init as PID 1 for signal forwarding |
stop_grace_period | stop_grace_period: 30s | Time between SIGTERM and SIGKILL (default 10s) |
pull_policy | pull_policy: always | always, missing (default), never, build |
platform | platform: linux/amd64 | Force an architecture |
user | user: "1000:1000" | Run as a specific UID:GID |
working_dir | working_dir: /app | Override WORKDIR |
entrypoint / command | command: ["npm", "run", "dev"] | Override image ENTRYPOINT / CMD |
tty / stdin_open | tty: true | Same as docker run -t / -i |
labels | labels: [traefik.enable=true] | Container labels (reverse proxies, tooling) |
configs | configs: [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
- Docker Cheat Sheet — Docker CLI, Dockerfile patterns, and image management
- Supply Chain Security — signing and verifying container images
- Kubernetes Cheat Sheet — when you outgrow Compose
- Observability Tools — adding monitoring to your Compose stack
Test Yourself
-
What command rebuilds images and starts all services?
docker compose up --build -
How do you start the core services plus those tagged with the
debugprofile?docker compose --profile debug up -
What
depends_oncondition waits for a health check to pass before starting a dependent service?condition: service_healthy -
What file is automatically merged with
compose.yamlwhen runningdocker compose up?compose.override.yaml -
How do you make a network internal-only (no internet access)? Set
internal: trueon the network definition. -
What Compose Watch action rebuilds the container when a file changes?
action: rebuild -
How do you run a one-off command in a new container without starting all services?
docker compose run service-name command -
What flag also removes named volumes when tearing down?
docker compose down -v -
How do you validate and view the fully resolved Compose configuration?
docker compose config -
Where are Docker Compose secrets mounted inside the container?
/run/secrets/secret-name
Common Gotchas
docker compose down -vdeletes your database data. Named volumes containing PostgreSQL, MySQL, or Redis data are permanently deleted. Only use-vwhen you want a fresh start.depends_onwithoutconditiononly 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 usecondition: service_healthyfor databases.- Putting passwords in
environment:in compose files. The compose file is committed to version control. Usesecrets:,env_file:with a.gitignoredfile, 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-orphansto clean up. --profileafter the subcommand fails.docker compose up --profile debugerrors withunknown flag; writedocker 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. Usedocker compose. Some distros ship adocker-composeshim that forwards to v2; scripts should still use the plugin form..envvsenv_file:..envfeeds${VAR}substitution in the YAML;env_file:sets variables inside the container. They are unrelated.container_nameblocks scaling. Two replicas cannot share a name, so--scaleanddeploy.replicasfail.- Editing
compose.yamldoes not change running containers. Rundocker compose up -dagain; Compose recreates only the services whose config changed. - Unquoted port mappings like
22:22can 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.