Anhang A: Spickzettel
Alles Wichtige aus Tag 1–15 auf wenigen Seiten. Die Zahl in Klammern
ist der Tag, an dem du es geübt hast. Im Zweifel gilt die
Compose-Referenz unter
docs.docker.com/reference/compose-file/ und die
CLI-Referenz unter
docs.docker.com/reference/cli/docker/compose/.
Die Muster-Datei
Kern der Lösung aus Anhang B: api mit Härtung und Secrets, ein
Migrations-Job und Postgres 18. worker und web folgen demselben Schema;
die vollständige Datei liegt in
code/anhb/loesung/compose.yaml.
# compose.yaml – Muster (Auszug)
name: notes
include:
- compose.tools.yaml # psql, backup mit Profil tools (7)
x-api-build: &api-build # ein Build für api und migrate (8)
context: notes-api
target: final
args:
VERSION: ${TAG:-dev}
x-hardening: &hardening # gemeinsame Härtung (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] # Dateien unter /run/secrets/ (10)
deploy:
resources:
limits:
cpus: "0.50"
memory: 64M
pids: 100 # nicht zusätzlich pids_limit (9)
ports:
- "127.0.0.1:${API_PORT:-8080}:8080" # nur lokal, Port per 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" # Einmal-Job: nie neu starten (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: nicht …/data (3)
configs:
- source: db_init
target: /docker-entrypoint-initdb.d/10-readonly.sql
networks: [backend] # keine 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 # kein Ausgang, kein Port-Publish (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
Befehle
| Befehl |
Zweck |
Tag |
docker compose up -d --wait |
starten, Exit 0 erst wenn alles gesund |
5 |
up -d --build / --force-recreate /
--no-deps |
neu bauen / neu erzeugen / ohne Abhängigkeiten |
1, 5 |
up -d --dry-run |
zeigt, was up täte, ändert nichts |
15 |
up --remove-orphans,
down --remove-orphans |
Container umbenannter Dienste entfernen |
15 |
ps -a --format json |
Zustand, Exit-Code, Ports als JSON |
1, 12 |
logs -f --since 5m --no-log-prefix api |
Logs eines Dienstes |
1, 12 |
exec db psql -U notes -d notes |
im laufenden Container |
1, 3 |
run --rm psql -c 'SELECT 1' |
Wegwerf-Container, auch mit Profil |
1, 7 |
port api 8080 |
veröffentlichte Adresse |
2, 15 |
stop / start / restart |
Container bleiben bestehen |
1 |
down / down -v |
entfernen / mit Volumes (Daten weg!) |
3 |
rm -sfv db |
einen Dienst samt anonymer Volumes entfernen |
3, 15 |
watch, up --watch |
develop.watch ausführen |
6 |
build --no-cache --pull,
--profile test build |
bauen |
8 |
ls --format json |
Projekte und ihre Dateien |
15 |
events --json, stats --no-stream,
top |
Beobachten |
12 |
docker compose config |
aufgelöste Datei – zeigt Secrets und Werte! |
1, 4 |
Projektname: -p bzw. COMPOSE_PROJECT_NAME
schlägt name:, das schlägt den Ordnernamen (1). Container
heißen <projekt>-<dienst>-1, Netze und Volumes
<projekt>_<name>.
Startreihenfolge
depends_on |
wartet bis |
Tag |
- db (kurz) |
Container gestartet – nicht bereit! |
5, 15 |
condition: service_started |
wie kurz |
5 |
condition: service_healthy |
Healthcheck meldet healthy |
5 |
condition: service_completed_successfully |
Container endet mit Exit 0 |
5 |
restart: true / required: false |
neu starten mit / Abhängigkeit optional |
5 |
restart: |
startet neu, wenn der Container endet … |
Tag |
"no" (Standard) |
nie – richtig für Jobs |
5 |
on-failure[:N] |
nur bei Exit-Code ungleich 0 |
5 |
unless-stopped |
immer, außer selbst gestoppt |
5 |
always |
immer, auch nach Daemon-Neustart |
5 |
Healthcheck-Felder: test (CMD ohne,
CMD-SHELL mit Shell), interval,
timeout, retries, start_period,
start_interval, disable: true. Ohne
healthcheck: gilt der HEALTHCHECK aus dem
Image. Docker startet unhealthy Container
nicht neu (5). Der Befehl muss im Image existieren:
wget in Alpine, kein curl (15).
Variablen und Konfiguration
environment:
NOTES_API_KEY: ${NOTES_API_KEY:?NOTES_API_KEY fehlt (.env)} # Pflicht
INTERVAL: ${WORKER_INTERVAL:-10} # Standardwert
LITERAL: "Preis: $$5" # $$ = ein $
Wer gewinnt beim Interpolieren ${…}? |
Tag |
1. Variable in der Shell (auch ein vergessenes
export!) |
4, 15 |
2. --env-file bzw. .env im
Projektordner |
4 |
3. Standardwert in der Datei (:-) |
4 |
| Wer gewinnt im Container? |
Tag |
1. docker compose run -e |
4 |
2. environment/env_file mit Wert aus Shell
oder .env interpoliert |
4 |
3. environment mit festem Wert |
4 |
4. env_file |
4 |
5. ENV im Image |
4 |
.env dient nur der Interpolation; in den Container
kommt nur, was in environment:/env_file: steht
(4).
configs: aus file: oder
content:, im Container als Datei (4, 11).
- Init-Skripte in
/docker-entrypoint-initdb.d und
POSTGRES_PASSWORD(_FILE) wirken nur bei
leerem Volume (4, 10, 15).
Mehrere Dateien
| Mechanismus |
Verhalten |
Tag |
compose.override.yaml |
wird ohne -f automatisch geladen – Vorsicht |
6, 15 |
-f a.yaml -f b.yaml, COMPOSE_FILE |
spätere Datei ergänzt/überschreibt |
7 |
!reset [] / !override |
Wert entfernen / komplett ersetzen |
7, 13 |
extends: psql |
Dienst erbt von einem anderen |
7 |
include: |
eigenes Teilprojekt, eigene .env, relative Pfade ab
seiner Datei |
7 |
profiles: [tools] |
nur mit --profile/COMPOSE_PROFILES oder
per run |
7 |
Achtung: Laut Doku meldet include
doppelte Ressourcen als Fehler; Compose 5.6.0 mischte sie im Test still
(7). up --wait wertet einen Dienst, der mit Exit 0 endet
und von dem niemand abhängt, als Fehler – Testdienste deshalb mit Profil
(Anhang B).
Entwickeln mit watch
action |
wirkt so |
Tag |
sync |
Dateien in den laufenden Container kopieren |
6 |
sync+restart |
kopieren, dann Container neu starten |
6 |
rebuild |
Image neu bauen, Container neu erzeugen |
6 |
target ist ein absoluter Pfad im Container; Compose
prüft nicht, ob die Anwendung dort liest (15). ignore: gilt
relativ zu path, .dockerignore gilt
zusätzlich.
- Löschen läuft als Container-User: Der
USER muss das
Ziel beschreiben dürfen (6).
watch liest die Datei nur beim Start; ohne
initial_sync kommt nur an, was sich danach ändert (6,
15).
Bauen
build:
context: notes-web
target: final # Stage aus dem Dockerfile
args:
VERSION: ${TAG:-dev}
secrets: [npmrc] # Build-Secret, nicht im Image (8)
image: ${COMPOSE_PROJECT_NAME}-web:${TAG:-dev}
- Ohne
image: heißt das Image
<projekt>-<dienst>. Mit image: und
build: baut Compose und taggt so; existiert das Image
schon, baut up ohne --build nicht (8).
- Gleiches
image: für api und migrate: ein Image, der
zweite Build kommt aus dem Cache (8). Compose 5.6.0 baut per Bake
(8).
Secrets und Härtung
| Quelle |
im Container |
Hinweis |
Tag |
file: ./secrets/x.txt |
/run/secrets/x (Bind-Mount) |
uid/gid/mode werden
ignoriert |
10 |
environment: VAR |
/run/secrets/x |
uid/gid/mode wirken |
10, 14 |
environment: im Dienst |
Umgebung |
sichtbar in Inspect und config |
4 |
- Anwendungen lesen
*_FILE
(NOTES_API_KEY_FILE, POSTGRES_PASSWORD_FILE)
(10).
- Ändert sich nur eine Secret-Datei, erzeugt
up -d nichts
neu: up -d --force-recreate <dienst> (10, 15).
- DB-Passwort rotieren:
ALTER ROLE → Secret-Dateien →
Clients neu erzeugen (10, 15).
- Härtung:
read_only + tmpfs,
cap_drop: [ALL], no-new-privileges,
deploy.resources.limits (cpus,
memory, pids), user:,
init: true (9). Exit 137 mit OOMKilled=true
heißt: Limit zu klein (9, 15).
Diagnose
# Zustand und 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}}'
# Warum unhealthy, warum Neustarts? (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
# Welche Dateien, welche Waisen? (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"}}'
# Was würde passieren – mit und ohne Shell-Variable? (4, 15)
docker compose up -d --dry-run
env -u NOTES_API_KEY docker compose up -d --dry-run
# Netze und Volumes (2, 3)
docker network inspect -f '{{.Internal}}' notes_backend
docker volume ls --filter label=com.docker.compose.project=notes
Fehlerbilder
| Symptom |
Ursache |
Fix |
port is already allocated |
anderer Container auf dem Port |
ps --filter publish=, Port per Variable (15) |
2. up grün, Port fehlt (8080/tcp) |
Container nach Bind-Fehler ohne Publish gestartet |
Konflikt lösen, neu erzeugen (15) |
0.0.0.0:3000->3000 |
Port ohne IP |
127.0.0.1:${…} (1, 15) |
api database unreachable, Exit 1 |
depends_on kurz |
service_healthy (5, 15) |
migrate connection refused trotz healthy db |
pg_isready ohne -h |
-h 127.0.0.1 (5, 15) |
db in 18+, … unused mount/volume |
Volume an …/data |
/var/lib/postgresql, rm -sfv (3, 15) |
401 trotz richtiger .env |
Variable in der Shell |
unset, env -u … --dry-run (4, 15) |
web als root, NODE_ENV=development |
compose.override.yaml |
entfernen, --build (6, 15) |
Found orphan containers, Netz „in use” |
Dienst umbenannt |
--remove-orphans (15) |
| „Syncing”, aber keine Änderung |
falsches target |
WORKDIR prüfen, watch neu starten (6, 15) |
Restarting (0), api Created |
Job mit restart-Policy |
restart: "no" (5, 15) |
28P01 nach Rotation |
Passwort nur im Secret geändert |
ALTER ROLE (10, 15) |
unhealthy, exec: "curl" |
Werkzeug fehlt im Image |
wget oder eigenes Binary (5, 15) |
Restarting (137) |
Speicherlimit |
Limit erhöhen (9, 15) |
ports: ohne Wirkung |
Dienst nur im internen Netz |
zusätzlich frontend (2, 15) |
can't set distinct values on 'pids_limit' |
pids_limit neben deploy.resources |
limits.pids (9) |