Docker Compose Cheatsheet

# Docker's apt repository
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

# Docker Engine, CLI, Buildx and Compose
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# RHEL 9 and rebuilds (dnf 4)
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

# Fedora 41 and later (dnf 5 changed the syntax)
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager addrepo --from-repofile=https://download.docker.com/linux/fedora/docker-ce.repo

# Then, on both
sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo systemctl enable --now docker      # start Docker now and at boot
sudo usermod -aG docker "$USER"          # use docker without sudo (log out and back in)
docker compose version                   # Docker Compose version v5.6.0
docker run --rm hello-world              # check that the daemon works

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p "$DOCKER_CONFIG/cli-plugins"
curl -fsSL "https://github.com/docker/compose/releases/download/v5.6.0/docker-compose-linux-$(uname -m)" \
  -o "$DOCKER_CONFIG/cli-plugins/docker-compose"
chmod +x "$DOCKER_CONFIG/cli-plugins/docker-compose"
docker compose version

brew install colima docker docker-compose
colima start

{
  "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"]
}

docker compose -f compose.yaml -f compose.prod.yaml up -d   # Merge two files
docker compose -p myproject up -d                           # Fixed project name
docker compose --env-file .env.prod up -d                   # Other variables file
docker compose --project-directory /path/to/project up -d   # Run from anywhere
docker compose up -d --dry-run                              # Preview: Running, Recreate, Create, ...

# Complete development reset (deletes the project's volumes)
docker compose down -v --remove-orphans && docker compose up -d --build

# Update one service without touching its dependencies
docker compose pull web && docker compose up -d --no-deps web

# Database shell and backup
docker compose exec db psql -U postgres -d myapp
docker compose exec -T db pg_dump -U postgres myapp > backup.sql

# Tests in a one-off container
docker compose run --rm --no-deps web npm test

# Validate, then start and wait for health checks
docker compose config --quiet && docker compose up -d --wait

# Save the last day of logs
docker compose logs --no-color --since 24h > app.log

# Compressed, dated Postgres backup
docker compose exec -T db pg_dump -U postgres myapp | gzip > backup-$(date +%F).sql.gz

# Restore it (into an existing, empty database)
gunzip -c backup-2026-10-11.sql.gz | docker compose exec -T db psql -U postgres myapp

# MySQL dump, with the password from inside the container
docker compose exec -T db sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" app' > dump.sql

# MariaDB 11 images have no mysqldump: use mariadb-dump
docker compose exec -T db sh -c 'exec mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" app' > dump.sql

# Back up a named volume to a tar file (stop the service first for a consistent copy)
docker compose stop db
docker run --rm -v myproject_db_data:/data -v "$PWD":/backup busybox tar czf /backup/db_data.tgz -C /data .
docker compose start db

# Restore it into a volume
docker run --rm -v myproject_db_data:/data -v "$PWD":/backup busybox tar xzf /backup/db_data.tgz -C /data

# Same command in every service
for s in $(docker compose ps --services); do docker compose exec -T "$s" hostname; done

# Stop every Compose project on the host
docker compose ls -q | xargs -I{} docker compose -p {} stop

# Pull newer images, recreate what changed, remove old untagged images
docker compose pull && docker compose up -d && docker image prune -f

# No "version:" key: it is obsolete and Compose warns "the attribute `version` is obsolete, it will be ignored"
name: myproject   # optional: the project name (otherwise the directory name)

services:
  web:
    image: nginx:latest
    # or build from Dockerfile
    build: .

  db:
    image: postgres:16

volumes:
  pgdata:

networks:
  frontend:
  backend:

services:
  app:
    # Image or build
    image: myapp:1.0
    build:
      context: .
      dockerfile: Dockerfile.prod
      args:
        - VERSION=1.0
      target: production          # multi-stage target

    # Container name (default: <project>-<service>-<n>, e.g. myproject-app-1); prevents scaling
    container_name: myapp

    # Networking
    ports:
      - "8080:80"                 # host:container
      - "127.0.0.1:9090:9090"     # bind to one host interface
      - "3000"                    # random host port
    expose:
      - "3000"                    # documents the port; no host mapping
    networks:
      - frontend
      - backend
    hostname: myapp.local
    dns:
      - 8.8.8.8
    extra_hosts:
      - "host.docker.internal:host-gateway"

    # Volumes
    volumes:
      - ./src:/app/src             # bind mount
      - pgdata:/var/lib/data       # named volume
      - /tmp/cache:/cache:ro       # read-only
    tmpfs:
      - /tmp

    # Environment
    environment:
      - NODE_ENV=production
      - DB_HOST=db
    env_file:
      - .env
      - .env.local

    # Commands
    command: ["npm", "start"]
    entrypoint: ["/docker-entrypoint.sh"]
    working_dir: /app

    # Dependencies
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

    # Health check
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

    # Restart policy
    restart: unless-stopped        # no | always | on-failure | unless-stopped

    # Resource limits (applied by docker compose, no swarm needed)
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.5"
          memory: 256M

    # Logging
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

    # Security
    user: "1000:1000"
    read_only: true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    security_opt:
      - no-new-privileges:true

    # Labels
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host(`app.example.com`)"

    # Misc
    stdin_open: true               # equivalent to -i
    tty: true                      # equivalent to -t
    init: true                     # docker-init (tini) as PID 1
    privileged: false
    pid: "host"                    # share host PID namespace
    platform: linux/amd64

volumes:
  # Named volume (Docker-managed)
  pgdata:

  # Named volume with driver options
  nfs-data:
    driver: local
    driver_opts:
      type: nfs
      o: "addr=nfs-server.example.com,rw"
      device: ":/path/to/share"

  # tmpfs volume (in RAM, gone when the container stops)
  cache:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

  # Bind a host directory as a named volume
  host_bind:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /host/path/to/data

  # External volume (must exist already), with its real name
  existing-data:
    external: true
    name: my_shared_volume

networks:
  # Default bridge network
  frontend:

  # Custom subnet
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

  # No outside connectivity: containers only talk to each other
  private:
    driver: bridge
    internal: true

  # External network (must exist already)
  proxy:
    external: true
    name: my_external_network

services:
  web:
    image: nginx:alpine
    networks:
      frontend:
        ipv4_address: 172.20.0.10

networks:
  frontend:
    ipam:
      config:
        - subnet: 172.20.0.0/16

services:
  web:
    image: nginx

  debug:
    image: busybox
    profiles:
      - debug

  test:
    image: myapp-test
    profiles:
      - test

services:
  app:
    image: myapp
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    environment: "API_KEY"        # value from the host's API_KEY variable

x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

services:
  web:
    <<: *common
    image: nginx

  app:
    <<: *common
    image: myapp

name: myproject                # project name

include:                       # merge another Compose file into this project
  - inc.yaml

services:
  app:
    extends:                   # reuse a service from another file
      file: base.yaml
      service: base
    environment:
      SHARED: app              # this file wins over the extended service
    pull_policy: never         # always | missing | never | build
    post_start:
      - command: sh -c "echo started > /tmp/post_start.txt"
    pre_stop:
      - command: sh -c "echo stopping > /tmp/pre_stop.txt"
    configs:
      - source: myconf
        target: /etc/myconf.txt

configs:
  myconf:
    content: |
      hello from configs       # inline file content, no separate file needed

services:
  app:
    image: myapp
    init: true                  # docker-init (tini) as PID 1: forwards signals, reaps zombies
    stop_signal: SIGTERM        # signal sent on stop (default SIGTERM)
    stop_grace_period: 30s      # wait before SIGKILL (default 10s)
    ulimits:
      nproc: 65535
      nofile:
        soft: 20000
        hard: 40000

services:
  app:
    image: myapp
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  syslog-app:
    image: myapp
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://192.168.0.42:514"

services:
  worker:
    image: busybox
    command: sleep 600
    develop:
      watch:
        - action: sync            # copy changed files into the container
          path: ./src
          target: /data/src
        # other actions: rebuild (rebuild the image and recreate), sync+restart

docker compose up -d                                             # compose.yaml + compose.override.yaml
docker compose -f compose.yaml -f compose.prod.yaml up -d        # base + production, no override

services:
  app:
    build: .
    ports:
      - "3000:3000"

services:
  app:
    volumes:
      - ./src:/app/src
    environment:
      - NODE_ENV=development
      - DEBUG=true

services:
  app:
    image: registry.example.com/myapp:latest
    restart: unless-stopped
    environment:
      - NODE_ENV=production
    deploy:
      resources:
        limits:
          memory: 512M

# .env
POSTGRES_VERSION=16
POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
APP_VERSION=1.0

services:
  db:
    image: postgres:${POSTGRES_VERSION:-16}    # default value
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?error message}  # required

  app:
    image: myapp:${APP_VERSION}

services:
  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/app
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d app"]
      interval: 10s
      timeout: 5s
      retries: 5

  cache:
    image: redis:alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

services:
  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret

volumes:
  db_data:

services:
  traefik:
    image: traefik:v3.0
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

  app:
    image: myapp
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host(`app.example.com`)"
      - "traefik.http.routers.app.entrypoints=websecure"
      - "traefik.http.services.app.loadbalancer.server.port=3000"
    restart: unless-stopped

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app

  app:
    build: .
    expose:
      - "3000"

services:
  app:
    build:
      context: .
      target: development
    volumes:
      - ./src:/app/src
      - /app/node_modules          # anonymous volume: keeps the image's node_modules
    ports:
      - "3000:3000"
      - "9229:9229"               # debugger port
    environment:
      - NODE_ENV=development
    command: ["npm", "run", "dev"]