Getting started

Introduction

Docker Compose defines and runs multi-container applications from a Compose file. This reference covers the Compose file format and CLI.

Basic example

compose.yaml

services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
    depends_on:
      - redis
  redis:
    image: redis:8

Compose reads compose.yaml by default; docker-compose.yml also works. The top-level version field is obsolete.

See: Compose quickstart

Compose versions

docker-compose up -d   # v1, retired
docker compose up -d   # current plugin

Compose v1 is retired; use the docker compose plugin (currently v5).

See: Compose release notes

Commands

CommandDescription
docker compose up -dCreate and start in background
docker compose up --waitWait for services to be running or healthy
docker compose downStop and remove containers and networks
docker compose psList project containers
docker compose logs -f webFollow service logs
docker compose exec web shRun a command in a service
docker compose run --rm web shRun a one-off command
docker compose buildBuild or rebuild images
docker compose pullPull service images
docker compose pushPush service images
docker compose restartRestart services
docker compose stop / startStop or start services
docker compose configRender the resolved configuration
docker compose lsList running projects
docker compose watchSync or rebuild on changes

Global flags: -f FILE, -p NAME, --profile NAME, --env-file FILE.

See: docker compose CLI reference

Services

Building and images

services:
  web:
    build: .
services:
  web:
    build:
      context: ./dir
      dockerfile: Dockerfile.dev
      args:
        APP_HOME: app

A context path builds from ./Dockerfile; the mapping form adds a Dockerfile and build arguments.

services:
  web:
    image: ghcr.io/example/app:1.0

image accepts a registry path, tag, or digest.

See: build

Ports

services:
  web:
    ports:
      - "3000"           # random host port
      - "8000:80"        # host:container
      - "127.0.0.1:8001:8001"
services:
  web:
    expose:
      - "3000"

Quote mappings to avoid YAML base-60 parsing. expose opens ports to linked services without publishing them.

See: ports and expose

Command and entrypoint

services:
  web:
    command: bundle exec thin -p 3000
services:
  web:
    entrypoint: ["/app/start.sh"]

command overrides the image's CMD; entrypoint overrides its ENTRYPOINT. Both accept a string or list.

See: command and entrypoint

Environment

services:
  web:
    environment:
      RACK_ENV: development
services:
  web:
    env_file:
      - .env
      - .development.env

Environment values can use a mapping or a list. env_file loads variables from files.

See: environment

Dependencies

services:
  web:
    depends_on:
      - db
services:
  web:
    depends_on:
      db:
        condition: service_healthy
        restart: true

Long syntax waits for health or successful completion and can restart dependents.

services:
  web:
    links:
      - db:database

Links add an alias and implicit dependency; networks are preferred.

See: depends_on and links

Runtime

Restart and resources

services:
  web:
    restart: unless-stopped
services:
  web:
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 512M

Policies: no, always, on-failure, unless-stopped. deploy.resources.limits caps CPUs and memory.

See: restart and deploy resources

Healthcheck

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

test accepts CMD, CMD-SHELL, or NONE; start_interval sets the probe rate during startup.

See: healthcheck

User

services:
  web:
    user: "1000:1000"

Runs the container process as the given user and group.

See: user

Devices

services:
  web:
    devices:
      - "/dev/ttyUSB0:/dev/ttyUSB0"

Maps host devices into the container.

See: devices

Labels

services:
  web:
    labels:
      com.example.description: "Accounting web app"

Labels add metadata to containers.

See: labels

Networking and storage

Networks

services:
  web:
    networks:
      - frontend
networks:
  frontend:

Creates a frontend network and attaches web to it.

See: networks

External networks

networks:
  frontend:
    external: true
    name: shared_frontend

external: true uses a network Compose does not create; name is its actual name.

See: external networks

DNS and hosts

services:
  web:
    dns:
      - 8.8.8.8
      - 8.8.4.4
    extra_hosts:
      - "somehost=192.168.1.100"

dns sets resolvers; extra_hosts adds /etc/hosts entries.

See: dns and extra_hosts

Volumes

services:
  db:
    image: postgres:18
    volumes:
      - dbdata:/var/lib/postgresql
volumes:
  dbdata:

Named volumes persist data; bind mounts use a host path such as ./data:/data.

See: volumes

Secrets

services:
  web:
    secrets:
      - my_secret
secrets:
  my_secret:
    file: ./my_secret.txt

Secrets mount at /run/secrets/<name> and are read-only.

See: secrets

Configs

services:
  web:
    configs:
      - http_config
configs:
  http_config:
    file: ./httpd.conf

Configs mount non-sensitive files at /<name> by default.

See: configs

services:
  web:
    external_links:
      - redis_1
      - project_db_1:mysql

Links containers from another Compose application.

See: external_links

Composition

Profiles

services:
  debug:
    image: busybox
    profiles: ["debug"]

Run with docker compose --profile debug up.

See: profiles

Watch

services:
  web:
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

Syncs files and rebuilds on changes. Run docker compose watch.

See: Compose Watch

Include

include:
  - common.yaml
services:
  web:
    image: nginx:stable

Loads another Compose file into the project. Include can also fetch OCI or Git sources.

See: include

Extends

services:
  web:
    extends:
      file: common.yml
      service: webapp

Reuses a service definition from another file.

See: extends

Merge overrides

compose.override.yaml

services:
  app:
    ports: !override
      - "8443:443"
    environment:
      FOO: !reset null

The override file merges into the base; !reset clears a value and !override replaces it instead of appending.

See: Merge Compose files

0 Comments for this cheatsheet. Write yours!