Skip to content
Hands-on IT IT Drills

Appendix A: Cheat Sheet

Everything important from Days 1–15 on a few pages. The number in parentheses is the day on which you practiced it. When in doubt, the Compose reference at docs.docker.com/reference/compose-file/ and the CLI reference at docs.docker.com/reference/cli/docker/compose/ are authoritative.

The model file

The core of the solution from Appendix B: api with hardening and secrets, a migration job and Postgres 18. worker and web follow the same pattern; the complete file is in code/anhb/loesung/compose.yaml.

# compose.yaml – model (excerpt)
name: notes

include:
  - compose.tools.yaml                  # psql, backup with profile tools (7)

x-api-build: &api-build                 # one build for api and migrate (8)
  context: notes-api
  target: final
  args:
    VERSION: ${TAG:-dev}

x-hardening: &hardening                 # shared hardening (9)
  read_only: true
  cap_drop: [ALL]
  security_opt: ["no-new-privileges:true"]

services:
  api:
    build: *api-build
    image: ${COMPOSE_PROJECT_NAME}-api:${TAG:-dev}
    <<: *hardening
    environment:
      NOTES_API_KEY_FILE: /run/secrets/api_key
      NOTES_DB_URL_FILE: /run/secrets/db_url
    secrets: [api_key, db_url]          # files under /run/secrets/ (10)
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 64M
          pids: 100                     # not additionally pids_limit (9)
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"   # local only, port via variable (1, 4)
    networks: [frontend, backend]
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    restart: unless-stopped

  migrate:
    build: *api-build
    image: ${COMPOSE_PROJECT_NAME}-api:${TAG:-dev}
    command: ["migrate"]
    <<: *hardening
    environment:
      NOTES_DB_URL_FILE: /run/secrets/db_url
    secrets: [db_url]
    networks: [backend]
    depends_on:
      db:
        condition: service_healthy
    restart: "no"                       # one-off job: never restart (5, 15)
    healthcheck:
      disable: true

  db:
    image: postgres:18.6-alpine
    environment:
      POSTGRES_USER: notes
      POSTGRES_DB: notes
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}
    volumes:
      - pgdata:/var/lib/postgresql      # Postgres 18: not …/data (3)
    configs:
      - source: db_init
        target: /docker-entrypoint-initdb.d/10-readonly.sql
    networks: [backend]                 # no ports:
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "notes", "-d", "notes"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 30s
      start_interval: 1s

networks:
  frontend: {}
  backend:
    internal: true                      # no egress, no port publishing (2)

volumes:
  pgdata: {}

configs:
  db_init:
    file: ./db/init/10-readonly.sql

secrets:
  api_key:
    file: ./secrets/api_key.txt
  db_url:
    file: ./secrets/db_url.txt

Commands

Command Purpose Day
docker compose up -d --wait start; exit 0 only once everything is healthy 5
up -d --build / --force-recreate / --no-deps rebuild / recreate / without dependencies 1, 5
up -d --dry-run shows what up would do, changes nothing 15
up --remove-orphans, down --remove-orphans remove containers of renamed services 15
ps -a --format json state, exit code, ports as JSON 1, 12
logs -f --since 5m --no-log-prefix api logs of one service 1, 12
exec db psql -U notes -d notes inside the running container 1, 3
run --rm psql -c 'SELECT 1' throwaway container, also with a profile 1, 7
port api 8080 published address 2, 15
stop / start / restart containers are kept 1
down / down -v remove / including volumes (data gone!) 3
rm -sfv db remove one service including anonymous volumes 3, 15
watch, up --watch run develop.watch 6
build --no-cache --pull, --profile test build build 8
ls --format json projects and their files 15
events --json, stats --no-stream, top observe 12
docker compose config resolved file – shows secrets and values! 1, 4

Project name: -p or COMPOSE_PROJECT_NAME beats name:, which beats the folder name (1). Containers are named <project>-<service>-1, networks and volumes <project>_<name>.

Startup order

depends_on waits until Day
- db (short) container started – not ready! 5, 15
condition: service_started like short 5
condition: service_healthy healthcheck reports healthy 5
condition: service_completed_successfully container ends with exit 0 5
restart: true / required: false restart along with it / dependency optional 5
restart: restarts when the container ends … Day
"no" (default) never – right for jobs 5
on-failure[:N] only with a non-zero exit code 5
unless-stopped always, unless stopped by you 5
always always, even after a daemon restart 5

Healthcheck fields: test (CMD without, CMD-SHELL with a shell), interval, timeout, retries, start_period, start_interval, disable: true. Without healthcheck:, the HEALTHCHECK from the image applies. Docker does not restart unhealthy containers (5). The command must exist in the image: wget in Alpine, no curl (15).

Variables and configuration

environment:
  NOTES_API_KEY: ${NOTES_API_KEY:?NOTES_API_KEY fehlt (.env)}  # required
  INTERVAL: ${WORKER_INTERVAL:-10}                             # default value
  LITERAL: "Preis: $$5"                                        # $$ = one $
Who wins during interpolation of ${…}? Day
1. Variable in the shell (including a forgotten export!) 4, 15
2. --env-file or .env in the project folder 4
3. Default value in the file (:-) 4
Who wins inside the container? Day
1. docker compose run -e 4
2. environment/env_file with a value interpolated from the shell or .env 4
3. environment with a fixed value 4
4. env_file 4
5. ENV in the image 4
  • .env is used for interpolation only; only what is in environment:/env_file: gets into the container (4).
  • configs: from file: or content:, as a file in the container (4, 11).
  • Init scripts in /docker-entrypoint-initdb.d and POSTGRES_PASSWORD(_FILE) only take effect with an empty volume (4, 10, 15).

Multiple files

Mechanism Behavior Day
compose.override.yaml loaded automatically without -f – careful 6, 15
-f a.yaml -f b.yaml, COMPOSE_FILE later file extends/overrides 7
!reset [] / !override remove value / replace completely 7, 13
extends: psql service inherits from another 7
include: its own sub-project, own .env, relative paths from its file 7
profiles: [tools] only with --profile/COMPOSE_PROFILES or via run 7

Warning: According to the docs, include reports duplicate resources as an error; in the test, Compose 5.6.0 merged them silently (7). up --wait treats a service that ends with exit 0 and that nobody depends on as an error – so give test services a profile (Appendix B).

Developing with watch

action effect Day
sync copy files into the running container 6
sync+restart copy, then restart the container 6
rebuild rebuild the image, recreate the container 6
  • target is an absolute path in the container; Compose doesn’t check whether the application reads from there (15). ignore: is relative to path; .dockerignore applies in addition.
  • Deletion runs as the container user: the USER must be able to write to the target (6).
  • watch reads the file only at startup; without initial_sync, only what changes afterwards gets through (6, 15).

Building

build:
  context: notes-web
  target: final            # stage from the Dockerfile
  args:
    VERSION: ${TAG:-dev}
  secrets: [npmrc]         # build secret, not in the image (8)
image: ${COMPOSE_PROJECT_NAME}-web:${TAG:-dev}
  • Without image:, the image is called <project>-<service>. With image: and build:, Compose builds and tags it that way; if the image already exists, up doesn’t build without --build (8).
  • The same image: for api and migrate: one image; the second build comes from the cache (8). Compose 5.6.0 builds via Bake (8).

Secrets and hardening

Source in the container Note Day
file: ./secrets/x.txt /run/secrets/x (bind mount) uid/gid/mode are ignored 10
environment: VAR /run/secrets/x uid/gid/mode take effect 10, 14
environment: in the service environment visible in inspect and config 4
  • Applications read *_FILE (NOTES_API_KEY_FILE, POSTGRES_PASSWORD_FILE) (10).
  • If only a secret file changes, up -d recreates nothing: up -d --force-recreate <service> (10, 15).
  • Rotating the DB password: ALTER ROLE → secret files → recreate clients (10, 15).
  • Hardening: read_only + tmpfs, cap_drop: [ALL], no-new-privileges, deploy.resources.limits (cpus, memory, pids), user:, init: true (9). Exit 137 with OOMKilled=true means: limit too small (9, 15).

Diagnosis

# state and ports (1, 2, 15)
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}\t{{.Ports}}'
docker compose port api 8080
docker ps --filter publish=8080 --format '{{.Names}}  {{.Ports}}'

# why unhealthy, why restarts? (5, 9, 15)
docker container inspect --format '{{json .State.Health.Log}}' notes-web-1 \
  | jq -r '.[-1].Output'
docker container inspect -f '{{.State.OOMKilled}} {{.RestartCount}}' notes-worker-1

# which files, which orphans? (7, 15)
docker compose ls --format json | jq -r '.[].ConfigFiles'
docker ps --filter label=com.docker.compose.project=notes \
  --format '{{.Names}}  {{.Label "com.docker.compose.project.config_files"}}'

# what would happen – with and without the shell variable? (4, 15)
docker compose up -d --dry-run
env -u NOTES_API_KEY docker compose up -d --dry-run

# networks and volumes (2, 3)
docker network inspect -f '{{.Internal}}' notes_backend
docker volume ls --filter label=com.docker.compose.project=notes

Failure patterns

Symptom Cause Fix
port is already allocated another container on the port ps --filter publish=, port via variable (15)
2nd up green, port missing (8080/tcp) container started without publish after bind error resolve conflict, recreate (15)
0.0.0.0:3000->3000 port without IP 127.0.0.1:${…} (1, 15)
api database unreachable, exit 1 depends_on short form service_healthy (5, 15)
migrate connection refused despite healthy db pg_isready without -h -h 127.0.0.1 (5, 15)
db in 18+, … unused mount/volume volume at …/data /var/lib/postgresql, rm -sfv (3, 15)
401 despite correct .env variable in the shell unset, env -u … --dry-run (4, 15)
web as root, NODE_ENV=development compose.override.yaml remove, --build (6, 15)
Found orphan containers, network “in use” service renamed --remove-orphans (15)
“Syncing”, but no change wrong target check WORKDIR, restart watch (6, 15)
Restarting (0), api Created job with restart policy restart: "no" (5, 15)
28P01 after rotation password changed only in the secret ALTER ROLE (10, 15)
unhealthy, exec: "curl" tool missing in the image wget or own binary (5, 15)
Restarting (137) memory limit raise the limit (9, 15)
ports: without effect service only in the internal network add frontend (2, 15)
can't set distinct values on 'pids_limit' pids_limit next to deploy.resources limits.pids (9)