Docker Compose Cheat Sheet (2026): every service key and CLI command

Overview

Docker Compose defines multi-container applications in a single YAML file. This cheat sheet covers the structure of compose.yaml, every service key, environment and configuration options, networking and volumes, the full CLI, override files, and profiles. All examples target Docker Compose v2 (the docker compose plugin) and the Compose Specification; the legacy version: key is obsolete and ignored.

compose.yaml structure

The basic structure of a Compose file:

services:      # Define containerized services
volumes:       # Define named volumes
networks:      # Define custom networks
configs:       # Define configs (for swarm, optional)
secrets:       # Define secrets (for swarm, optional)

Services: basic keys

Networking and ports

Environment and configuration

Storage: volumes and bind mounts

Note: Define named volumes at the top level:

volumes:
  my_data:
    driver: local

Resource limits

Health checks

Full example:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 5s
  start_period: 10s
  retries: 3

Dependencies and startup order

Caution: condition: service_healthy requires the service to have a healthcheck. Without it, the condition fails immediately.

Full example:

services:
  web:
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

Security: secrets and configs

Top-level definition:

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

configs:
  nginx_config:
    file: ./nginx.conf

Access in container:

# In shell: cat /run/secrets/db_password

Profiles

Profiles allow you to conditionally include services.

services:
  web:
    image: nginx:latest
    # Always included

  debug:
    image: busybox:latest
    profiles: [debug]
    # Only included with --profile debug

  monitoring:
    image: prom/prometheus:latest
    profiles: [monitoring, prod]
    # Included with --profile monitoring OR --profile prod

Usage:

docker compose up                        # Include only services without profiles
docker compose --profile debug up        # Include web + debug
docker compose --profile monitoring up   # Include web + monitoring
docker compose --profile debug --profile monitoring up  # Include all three

Networks (top-level)

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br0

Service usage:

services:
  web:
    networks: [frontend, backend]
  db:
    networks: [backend]

Volumes (top-level)

volumes:
  db_data:
    driver: local
  shared_cache:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

Override files

Docker Compose automatically loads docker-compose.override.yaml and merges it with compose.yaml.

compose.yaml (production):

services:
  web:
    image: myapp:latest
    environment:
      LOG_LEVEL: warn

docker-compose.override.yaml (local development):

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      LOG_LEVEL: debug

Result when running docker compose up:
– Image is built from ./Dockerfile (overrides image: myapp:latest)
– Port 8000 is exposed on the host
– LOG_LEVEL is set to debug
– Port mapping and LOG_LEVEL are merged

Explicit override file:

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

CLI commands

Patterns you’ll reuse

# Development with override file
# compose.yaml: production setup
# docker-compose.override.yaml: local dev tweaks

# Database with healthcheck and depends_on
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

# Multi-tier application
services:
  web:
    networks: [frontend, backend]
  cache:
    networks: [backend]
  db:
    networks: [backend]

# Load environment from file with overrides
services:
  app:
    env_file: .env
    environment:
      LOG_LEVEL: debug  # Override from .env

# Profiles for optional services
  monitoring:
    profiles: [monitoring]
  debug:
    profiles: [debug]

# Use compose watch for live reload (Compose 2.22+)
# docker compose watch
watch:
  - path: ./src
    action: sync
    target: /app/src
  - path: ./requirements.txt
    action: rebuild

FAQ

What’s the difference between docker-compose.yml and compose.yaml?

Both are supported. Docker prefers compose.yaml (no dash). Both are equivalent; pick one convention and stick with it. Modern documentation uses compose.yaml.

How do I set environment variables in Docker Compose?

Use the environment key in a service, or load from a file with env_file: .env. Variables can be hardcoded, from the host shell (${VAR_NAME}), or from .env files. Use secrets for sensitive values.

How do I ensure one service starts before another?

Use depends_on: db: condition: service_healthy (requires a HEALTHCHECK). For just startup order without validation, use the short form depends_on: [db]; it only orders startup and does not wait for readiness.

How do I use Docker Compose override files?

Create docker-compose.override.yaml in the same directory. Compose automatically loads it and merges it with compose.yaml. Override specific services without editing the main file. Useful for local development vs. production.

What are Docker Compose profiles?

Profiles allow you to conditionally include services. Set profiles: [debug] on a service, then use docker compose --profile debug up to include it. Useful for optional debugging services or monitoring stacks.