Docker Compose Reference

Defines the set of containers in the application. Each key is a service name.

services:
  web:
    image: nginx:alpine
  db:
    image: postgres:16

Declares named volumes shared between services. Can be backed by a driver or marked external.

volumes:
  pgdata:
  uploads:
    driver: local

Declares named networks. Services are connected to their listed networks. Default driver is bridge.

networks:
  frontend:
  backend:
    internal: true

Specifies the image to start the container from. Cannot be used with build at the same time.

services:
  web:
    image: nginx:1.25-alpine

Configures build-time options. Short form is a path to the Dockerfile context. Long form supports context, dockerfile, args, target.

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile.prod
      args:
        VERSION: "1.2.3"

Maps container ports to the host. Short syntax: HOST:CONTAINER. Can also specify protocol (tcp/udp).

services:
  web:
    ports:
      - "80:80"
      - "443:443"
      - "127.0.0.1:5432:5432"

Sets environment variables in the container. Map or list syntax. Use env_file to load from files.

services:
  api:
    environment:
      NODE_ENV: production
      PORT: 3000
      DATABASE_URL: postgres://db/app

Loads environment variables from one or more .env files. Variables are not accessible during the build step.

services:
  api:
    env_file:
      - .env
      - .env.local

Mounts host paths or named volumes into the container. Short syntax: SOURCE:TARGET[:MODE].

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

Express startup dependencies between services. Long form supports condition: service_healthy to wait for healthchecks.

services:
  api:
    depends_on:
      db:
        condition: service_healthy

Connects the service to named networks. If omitted, the service joins the default network.

services:
  api:
    networks:
      - frontend
      - backend

Restart policy: no (default), always, on-failure, unless-stopped.

services:
  worker:
    restart: unless-stopped

Configures a health test for the container. test is a command list; interval, timeout, retries control the behaviour.

services:
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Overrides the default CMD from the image. String or list form.

services:
  worker:
    command: python manage.py rqworker default

Assigns profiles to a service. Services with profiles are only started when the profile is active (--profile flag or COMPOSE_PROFILES env var).

services:
  debug-tools:
    image: nicolaka/netshoot
    profiles: [debug]

Number of container replicas (Swarm only). Ignored by docker compose without --compatibility flag.

services:
  web:
    deploy:
      replicas: 3
      update_config:
        parallelism: 1

Marks a volume as externally managed. Compose will not create or remove it; it must exist before the stack is started.

volumes:
  secrets:
    external: true

Restricts external access to the network. Containers on an internal network can only communicate with each other.

networks:
  backend:
    internal: true