Docker Compose

What a Compose File Becomes

Key Numbers

A Real-World compose.yml

name: myapp
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    depends_on:
      api:
        condition: service_healthy
    networks: [front, back]
    restart: unless-stopped

  api:
    build:
      context: ./api
      target: production       # multi-stage target
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
    env_file:
      - .env.production
    secrets:
      - jwt_signing_key
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 30s
    networks: [back]
    deploy:
      resources:
        limits: { cpus: '2', memory: 1G }

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/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: 5s
      timeout: 3s
      retries: 5
    networks: [back]

  pgadmin:
    image: dpage/pgadmin4
    ports: ["5050:80"]
    profiles: [tools]          # only with --profile tools
    networks: [back]

networks:
  front:
  back:

volumes:
  pgdata:

secrets:
  db_password:
    file: ./secrets/db_password.txt
  jwt_signing_key:
    file: ./secrets/jwt.pem

Service Networks

# Compose creates a per-project bridge network by default.
# Services on the same network can resolve each other by name.

$ docker network ls --filter label=com.docker.compose.project=myapp
NETWORK ID     NAME             DRIVER    SCOPE
abc123def456   myapp_back       bridge    local
def789abc012   myapp_front      bridge    local

# Inside 'api' container, 'db' resolves to db's IP via Docker's embedded DNS
api$ getent hosts db
172.20.0.5      db

# Cross-network communication: only services on shared networks can talk.
# 'web' is on front+back; 'pgadmin' is on back only — they CAN talk.
# 'web' and a service on a third network CANNOT talk.

Healthchecks and depends_on Conditions

depends_on:
  db:
    condition: service_healthy   # wait for db's healthcheck to pass
  cache:
    condition: service_started   # default: wait for container to start
  init:
    condition: service_completed_successfully  # wait for one-shot to exit 0

# Healthcheck states: starting, healthy, unhealthy
$ docker inspect <cid> --format '{{.State.Health.Status}}'
healthy

# Common patterns
healthcheck:
  test: ["CMD-SHELL", "wget -qO- http://localhost/health || exit 1"]
  interval: 30s        # how often
  timeout: 5s          # max time per check
  retries: 3           # consecutive failures before unhealthy
  start_period: 60s    # grace period during which failures don't count

Profiles

services:
  app:
    image: myapp
  db:
    image: postgres:16
  pgadmin:
    profiles: [tools]
    image: dpage/pgadmin4
  load-test:
    profiles: [test]
    image: myapp-loadtest

# Default: only 'app' and 'db' come up
$ docker compose up

# Add the tools profile
$ docker compose --profile tools up
# Now app + db + pgadmin

# Multiple profiles
$ docker compose --profile tools --profile test up

Watch Mode (v2.22+)

services:
  api:
    build: ./api
    develop:
      watch:
        - action: sync
          path: ./api/src
          target: /app/src
          ignore:
            - node_modules/
        - action: rebuild
          path: ./api/package.json

# Run with watch
$ docker compose up --watch
# Editing api/src/server.js syncs into the container; nodemon restarts.
# Editing api/package.json triggers a full rebuild.

Compose vs Kubernetes

Tradeoffs

Frequently Asked Questions