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) |