Docker Compose

docker compose config                     # merged result after overrides and ${VAR} interpolation
docker compose config --services          # service names only
docker compose -p feature-x up -d         # isolated copy of the same file
docker compose ls                         # every project running on this daemon

docker compose up -d                      # create or update to match the file
docker compose up -d --wait --wait-timeout 120   # block until running, or healthy where a healthcheck exists
docker compose up -d --no-deps web        # only this service, leave its dependencies alone
docker compose stop                       # stop processes, keep containers
docker compose start
docker compose restart web                # restarts the process; does not apply file changes
docker compose down                       # remove containers and the default network
docker compose down --remove-orphans      # also remove containers for services no longer in the file

docker compose up -d --wait --wait-timeout 120
./run-tests
docker compose down -v

name: my-app

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        APP_ENV: production
    image: registry.example.com/web:1.0    # tag for the built image, or the image to pull
    command: ["server", "--port", "8080"]  # replaces the image CMD
    ports:
      - "127.0.0.1:8080:8080"              # host_ip:host_port:container_port
    environment:
      DB_HOST: db
      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
    env_file:
      - path: ./web.env
        required: false                   # skip silently when the file is missing
    volumes:
      - ./src:/app/src:ro,Z                # bind mount; Z relabels for SELinux
      - webdata:/app/data
    depends_on:
      db:
        condition: service_healthy
        restart: true                      # restart web when db is restarted by Compose
      migrate:
        condition: service_completed_successfully
    restart: unless-stopped
    user: "10001:10001"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/health"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 30s
    deploy:
      resources:
        limits: { cpus: "1.5", memory: 512M }

  migrate:
    image: registry.example.com/web:1.0
    command: ["./migrate"]
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:?}
    volumes:
      - dbdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10

volumes:
  webdata:
  dbdata:

docker compose --env-file .env.staging config     # check interpolation before applying
docker compose config --environment               # show the variables used for interpolation

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d        # also start services tagged with the debug profile

# compose.prod.yaml: only the differences
services:
  web:
    build: !reset null                       # use the registry image, never build in prod
    ports: !override
      - "8080:8080"
    environment:
      LOG_LEVEL: warn

services:
  web:
    image: registry.example.com/web:1.0
  db:
    image: postgres:17
    profiles: [local-db]
  pgadmin:
    image: dpage/pgadmin4:9
    profiles: [debug, local-db]
  loadgen:
    image: grafana/k6:1.0.0
    profiles: [test]
    depends_on: [web]

docker compose up -d                         # web only
docker compose --profile local-db up -d      # web, db, pgadmin
COMPOSE_PROFILES=debug,test docker compose up -d
docker compose --profile '*' config --services   # every service regardless of profile
docker compose run --rm loadgen run /scripts/smoke.js   # naming a profiled service on the command line activates it implicitly
docker compose --profile local-db down       # down without the profile leaves db running and warns about orphans

# compose.yaml
include:
  - path: ../shared/observability/compose.yaml      # its relative paths resolve against its own directory
    project_directory: ../shared/observability
    env_file: ../shared/observability/.env           # interpolation for that file only
  - ./compose.db.yaml                                 # short form

services:
  web:
    extends:
      file: ./common.yaml
      service: app-base
    image: registry.example.com/web:1.0
    command: ["server"]
  worker:
    extends:
      file: ./common.yaml
      service: app-base
    command: ["worker"]

# common.yaml: never run directly
services:
  app-base:
    restart: unless-stopped
    user: "10001:10001"
    read_only: true
    tmpfs: [/tmp]
    logging:
      driver: local
      options: { max-size: 20m }
    env_file:
      - path: ./app.env
        required: false

services:
  migrate:
    image: registry.example.com/web:1.0
    command: ["./migrate", "up"]
    restart: "no"                        # a one-shot must not restart, or it never "completes"
    depends_on:
      db: { condition: service_healthy }
  web:
    depends_on:
      migrate: { condition: service_completed_successfully }
      db: { condition: service_healthy, restart: true }
      cache: { condition: service_started, required: false }   # optional dependency (2.20+)

docker compose config | grep -A5 'environment:'     # the resolved values that will reach the container
docker compose run --rm web env | sort               # what the process sees, including image ENV
docker compose --env-file .env.staging config --environment   # interpolation variables and where they came from
COMPOSE_ENV_FILES=.env,.env.local docker compose up -d        # several interpolation files (2.24+)

services:
  web:
    image: registry.example.com/web@sha256:0123abcd...   # digest pin
    pull_policy: always                                  # or missing (default), never, build, daily, weekly, every_12h
    user: "10001:10001"
    read_only: true
    tmpfs:
      - /tmp:size=64m,noexec,nosuid
    cap_drop: [ALL]
    cap_add: [NET_BIND_SERVICE]
    security_opt:
      - no-new-privileges:true
    init: true                                          # tini-style PID 1 for signal forwarding and zombie reaping
    stop_grace_period: 30s                              # SIGTERM to SIGKILL window; default 10s
    stop_signal: SIGINT
    pids_limit: 256
    ulimits:
      nofile: { soft: 65536, hard: 65536 }
    shm_size: 256m
    deploy:
      resources:
        limits: { cpus: "1.5", memory: 512M, pids: 256 }
        reservations: { memory: 256M }
    logging:
      driver: journald
      options: { tag: "{{.Name}}" }
    networks:
      frontend:
        aliases: [web.internal]
      backend:
    dns: [192.0.2.53]
    extra_hosts:
      - "host.docker.internal:host-gateway"

networks:
  frontend:
  backend:
    internal: true                                      # no route to the outside; only services on it can talk

docker compose exec web sh                     # inside the existing container
docker compose run --rm web ./migrate          # new container from the service definition
docker compose run --rm --service-ports web    # same, and publish the service's ports
docker compose cp web:/app/report.csv .
docker compose logs -f --since 10m web db
docker compose top                             # processes per container
docker compose events --json                   # stream container lifecycle events

# Every unhealthy container in the project
docker compose ps --format json | jq -r 'select(.Health=="unhealthy") | .Name'

# Image each container is actually running
docker compose ps -q | xargs docker inspect -f '{{.Name}} {{.Image}}'

# Diff the merged config between two override sets
diff <(docker compose -f compose.yaml config) <(docker compose -f compose.yaml -f compose.prod.yaml config)

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

# Volumes belonging to this project
docker compose volumes

# Wait for one service without --wait
until [ "$(docker inspect -f '{{.State.Health.Status}}' "$(docker compose ps -q db)")" = healthy ]; do sleep 1; done

# Services and the profiles that enable them
docker compose --profile '*' config --format json | jq -r '.services | to_entries[] | "\(.key)\t\(.value.profiles // ["-"] | join(","))"'

# Services that would be created for the current profiles
docker compose config --services

# Validate the file without starting anything, including interpolation failures
docker compose config -q && echo valid

# Show a service's resolved environment as it will reach the container
docker compose config --format json | jq '.services.web.environment'

# Images the file references, for scanning or mirroring
docker compose config --images

# Pin every image to its current digest in a copy of the config
docker compose config --resolve-image-digests > compose.pinned.yaml

# Which host ports the project publishes
docker compose ps --format json | jq -r '.Name as $n | .Publishers[]? | select(.PublishedPort > 0) | "\($n) \(.URL):\(.PublishedPort)->\(.TargetPort)"' | sort -u

# Exit code of a one-shot service (tests, migrations) after up
docker compose up --exit-code-from tests --abort-on-container-exit tests; echo "rc=$?"

# Run migrations then start the stack in one line
docker compose run --rm migrate && docker compose up -d --wait

# Recreate only containers whose configuration changed, pulling newer images first
docker compose up -d --pull always --remove-orphans

# Restart the process of every service without recreating (no config changes applied)
docker compose restart

# Tail logs for the whole project since the last deploy time
docker compose logs --since "$(docker inspect -f '{{.Created}}' "$(docker compose ps -q web)")"

# Show the hash Compose uses to decide recreation, per service
docker compose config --hash '*'

# Disk used by this project's volumes
docker system df -v | awk -v p="$(docker compose config --format json | jq -r .name)_" '/^VOLUME NAME/ {f = 1; next} f && index($1, p) == 1 {print $1, $3}'

# Copy the project's .env variables into the current shell (for scripts that call docker directly)
set -a; . ./.env; set +a

# Stop everything gracefully with a longer drain window than the file allows
docker compose stop -t 60

# Second isolated copy of the stack on different ports via an override
docker compose -p review-42 -f compose.yaml -f compose.review.yaml up -d

# Attach the project network to a debugging container
docker run --rm -it --network "$(docker compose config --format json | jq -r .name)_default" nicolaka/netshoot

# Delete the project completely: containers, networks, named volumes and locally built images (data loss)
docker compose down -v --rmi local --remove-orphans

#!/usr/bin/env bash
# usage: deploy.sh SERVICE NEW_TAG    (compose.yaml uses image: registry.example.com/web:${IMAGE_TAG})
set -euo pipefail

svc=${1:?service} new=${2:?new tag}
cid=$(docker compose ps -q "$svc" || true)
old=$(if [[ -n $cid ]]; then docker inspect -f '{{.Config.Image}}' "$cid" | sed 's/.*://'; fi)
export IMAGE_TAG=$new

docker compose pull -q "$svc"
if docker compose up -d --no-deps --wait --wait-timeout 120 "$svc"; then
  printf 'deployed %s:%s\n' "$svc" "$new"
  exit 0
fi

printf 'health gate failed for %s:%s\n' "$svc" "$new" >&2
docker compose logs --tail 50 "$svc" >&2 || true
if [[ -n $old ]]; then
  printf 'rolling back to %s\n' "$old" >&2
  IMAGE_TAG=$old docker compose up -d --no-deps --wait --wait-timeout 120 "$svc"
fi
exit 1

#!/usr/bin/env bash
# usage: compose-report.sh
set -euo pipefail

now=$(date +%s)
printf '%-20s %-28s %-10s %-10s %8s %6s\n' PROJECT SERVICE STATE HEALTH RESTARTS IMGAGE
docker ps -a --filter label=com.docker.compose.project -q | while read -r id; do
  docker inspect "$id" | jq -r --argjson now "$now" '.[0] |
    [ .Config.Labels["com.docker.compose.project"],
      .Config.Labels["com.docker.compose.service"],
      .State.Status,
      (.State.Health.Status // "-"),
      (.RestartCount | tostring),
      ((($now - (.Created | sub("\\.[0-9]+"; "") | fromdate)) / 86400 | floor | tostring) + "d") ] | @tsv'
done | sort | awk -F'\t' '{printf "%-20s %-28s %-10s %-10s %8s %6s\n", $1, $2, $3, $4, $5, $6}'

#!/usr/bin/env bash
# usage: compose-backup.sh DEST_DIR   (run from the project directory)
set -euo pipefail

dest=${1:?destination}; mkdir -p "$dest"
project=$(docker compose config --format json | jq -r .name)
stamp=$(date +%Y%m%dT%H%M%S)
mapfile -t vols < <(docker volume ls -q --filter "label=com.docker.compose.project=$project")
(( ${#vols[@]} )) || { echo "no named volumes for project $project" >&2; exit 0; }

docker compose stop
trap 'docker compose start >/dev/null' EXIT          # restart even if a copy fails
for v in "${vols[@]}"; do
  out=$dest/$v-$stamp.tar.zst
  docker run --rm -v "$v:/data:ro" -v "$dest:/backup" alpine:3.24 \
    sh -c 'apk add --no-cache zstd >/dev/null && tar -C /data -cf - . | zstd -T0 -q > "/backup/$0"' "$(basename "$out")"
  printf '%s %s\n' "$(du -h "$out" | cut -f1)" "$out"
done