Zum Inhalt springen
Trainingslager IT-Trainingslager

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)