Docker Compose YAML

Minimal compose.yaml

The smallest useful Compose file: a web server and a database. No version: field is required - it has been obsolete since Compose v2:

# compose.yaml - minimal web + database
services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret

Run docker compose up -d in the directory to bring the stack online, docker compose ps to see the running containers, and docker compose down to tear it down.

Production-grade example

A more complete file with build context, healthchecks, named volumes, named networks, secrets, and image pinning:

# compose.yaml - production-grade example
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: myorg/web:1.4.0
    ports:
      - "80:8080"
    environment:
      NODE_ENV: production
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    networks:
      - frontend
      - backend

  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

volumes:
  db_data:

networks:
  frontend:
  backend:

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

Highlights:

• Image pinning - postgres:16, nginx:1.27 rather than :latest. Reproducible builds depend on it.
• Healthchecks - both containers expose them sodepends_on.condition: service_healthy is meaningful.
• Named volumes - db_data survivesdocker compose down; bind mounts would not.
• Named networks - explicit frontend / backend networks let you isolate which services can talk to each other.
• Secrets - the database password lives in a file the container reads at startup, not in the compose file.

env_file vs environment

environment: sets variables inline. Use it for values that belong with the service definition. env_file: loads from an external file - use it for secrets and per-environment differences:

# .env (sibling of compose.yaml)
NODE_ENV=production
DATABASE_URL=postgres://app:secret@db:5432/app
LOG_LEVEL=info

Compose loads .env from the directory of the compose file. Inline environment: values override env_file values for the same key.

depends_on with healthchecks

Plain depends_on only controls start order - the dependent container starts as soon as the dependency starts, not when it is ready. For a database, that is too soon. Pair with a healthcheck and the service_healthy condition:

# Wait for db to be healthy before starting api
services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    image: myorg/api:1.4.2
    depends_on:
      db:
        condition: service_healthy

Profiles for optional services

A profile gates a service behind a CLI flag. Use profiles for dev-only tooling, optional workers, or debug containers that should not start by default:

# Run subsets of services with --profile
services:
  web:
    image: myorg/web:latest
    # always runs - no profile

  worker:
    image: myorg/worker:latest
    profiles: ["worker"]

  debug:
    image: nicolaka/netshoot
    profiles: ["debug"]
    network_mode: "service:web"
# docker compose up                  # only web
# docker compose --profile worker up # web + worker
# docker compose --profile debug up  # web + debug

DRY with YAML anchors

Compose supports YAML anchors and merge keys directly. The x- prefix tells Compose to ignore the top-level key, so it exists only to host the anchor:

# DRY: share env across services with anchors
x-shared-env: &shared-env
  TZ: UTC
  LOG_LEVEL: info

services:
  web:
    image: myorg/web:latest
    environment:
      <<: *shared-env
      ROLE: web

  worker:
    image: myorg/worker:latest
    environment:
      <<: *shared-env
      ROLE: worker

Full reference on the YAML anchors page, including merging multiple anchors and the deep-merge gotcha.

compose.yaml vs docker-compose.yml

• compose.yaml - canonical filename per the Compose Specification. Use it for new projects.
• docker-compose.yml - legacy filename. Still recognized by Docker Compose v2 for backward compatibility.
• Either extension works - .yaml or .yml. See YML vs YAML for the full comparison.
• If both compose.yaml and docker-compose.yml exist in the same directory, Compose loads compose.yaml.

Validate before you ship

docker compose config resolves the file (including anchor expansion and env substitution) and prints the canonical YAML the engine will use - the fastest way to spot bugs. For syntax-level checks, drop the file into the YAML validator. For Kubernetes-style manifests, see the Kubernetes YAML page.