Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 5: Startreihenfolge

Ziel: Der Stack startet mit einem Befehl in der richtigen Reihenfolge – Postgres bereit, Tabelle angelegt, dann api, dann worker und web. · Dauer: ca. 75 min · Voraussetzung: Tag 4

Briefing

  • depends_on in der kurzen Form wartet nur, bis der andere Container läuft, nicht bis er bereit ist. Das ist die Race von Tag 0.
  • Die lange Form kennt drei Bedingungen: service_started, service_healthy und service_completed_successfully.
  • „Bereit” definiert ein Healthcheck: Postgres bekommt einen mit pg_isready, notes-api bringt ihren eigenen im Image mit.
  • Die Tabelle legt ein Einmal-Job migrate an. api startet erst, wenn er mit Exit 0 endet.
  • restart: regelt, was nach einem Absturz passiert; up --wait meldet per Exit-Code, ob alles gesund ist.
 db ──healthy──► migrate ──Exit 0──► api ──healthy──► worker
  │                                   ▲          └──healthy──► web
  └───────────────healthy─────────────┘

Drill 1: Die Race in Compose

Tagesstart wie immer, Stack von Tag 4 abräumen, Stand von Tag 4 holen:

source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag05 && cd ~/compose-lab/tag05
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag04/notes/." .

An Tag 3 und 4 hast du Postgres von Hand abgewartet. Jetzt mit leerem Volume und ohne Warten – down -v löscht dazu das Volume notes_pgdata dieses Projekts:

docker compose down -v
docker compose up -d
sleep 5
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'
docker compose logs api | tail -1

Erwartet (gekürzt, IDs, Adressen und Zeiten weichen bei dir ab):

 Container notes-db-1 Started
 Container notes-api-1 Started
 Container notes-web-1 Started
 Container notes-worker-1 Started
SERVICE   STATUS
api       Exited (1) 5 seconds ago
db        Up 5 seconds
web       Up 5 seconds
worker    Up 5 seconds
api-1  | time=… level=ERROR msg="database unreachable" source=env err="failed to connect
to `user=notes database=notes`:\n\t172.21.0.2:5432 (db): dial error: dial tcp
172.21.0.2:5432: connect: connection refused…"

Compose hat db gestartet und danach sofort api – genau das verspricht depends_on in der kurzen Form. Postgres initialisierte noch, api endete mit Exit 1, und worker und web laufen ins Leere.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Wann ist Postgres bereit?

pg_isready prüft, ob der Server Verbindungen annimmt (Exit 0 = ja, 1 = lehnt ab, 2 = keine Antwort). Frag zehnmal pro Sekunde – einmal über den Unix-Socket (Standard), einmal über TCP wie api:

docker compose down -v
docker compose up -d db
docker compose exec db sh -c 'for i in $(seq 1 60); do
  pg_isready -q -U notes -d notes; s=$?
  pg_isready -q -h 127.0.0.1 -U notes -d notes; t=$?
  echo "Socket: $s  TCP: $t"
  sleep 0.1
done' | uniq -c
docker compose logs db | grep -E 'listening on|ready to accept'

Erwartet (gekürzt, Zeiten und Zahlen weichen ab):

   7 Socket: 2  TCP: 2
   1 Socket: 0  TCP: 2
   1 Socket: 2  TCP: 2
  51 Socket: 0  TCP: 0
db-1  | … [75] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db-1  | … [75] LOG:  database system is ready to accept connections
db-1  | … [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
db-1  | … [1] LOG:  listening on IPv6 address "::", port 5432
db-1  | … [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db-1  | … [1] LOG:  database system is ready to accept connections

Die zweite Zeile ist die Falle: Bei einem leeren Volume startet das Image erst einen temporären Server (PID 75) nur auf dem Socket, führt die Init-Skripte aus (Tag 4), stoppt ihn und startet dann den echten (PID 1) auf TCP. Ein pg_isready ohne -h meldet in diesem Moment „bereit”, obwohl api noch nicht hinkommt. Das Fenster ist kurz – genau die Sorte Fehler, die nur jeder zwanzigste CI-Lauf trifft.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Healthcheck für db

Ergänze den Dienst db in compose.yaml (die übrigen Zeilen bleiben):

  db:
    image: postgres:18.6-alpine
    restart: unless-stopped
    # … environment, volumes, configs, networks wie an Tag 4 …
    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
Attribut Bedeutung
test Befehl im Container; Exit 0 = gesund. CMD ohne Shell, CMD-SHELL mit sh -c
interval / timeout Abstand zwischen zwei Prüfungen / Höchstdauer einer Prüfung
retries so viele Fehlschläge in Folge, dann unhealthy
start_period / start_interval Anlaufzeit, in der Fehlschläge nicht zählen / Takt in dieser Zeit
docker compose config -q; echo "Exit: $?"
docker compose down -v
docker compose up -d --wait db
docker compose ps db --format 'table {{.Service}}\t{{.Status}}'
docker inspect --format '{{json .State.Health}}' notes-db-1 \
  | jq '{Status, FailingStreak, Log: [.Log[] | {ExitCode, Output}]}'

Erwartet (gekürzt):

Exit: 0
 Container notes-db-1 Started
 Container notes-db-1 Waiting
 Container notes-db-1 Healthy
SERVICE   STATUS
db        Up 2 seconds (healthy)
{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "ExitCode": 2,
      "Output": "127.0.0.1:5432 - no response\n"
    },
    {
      "ExitCode": 0,
      "Output": "127.0.0.1:5432 - accepting connections\n"
    }
  ]
}

Dank start_interval: 1s prüft Docker in der Anlaufzeit jede Sekunde statt alle fünf – db ist nach rund zwei Sekunden healthy. Der Fehlschlag mit Exit 2 zählt nicht, er lag in der start_period.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Migration als Einmal-Job

Neuer Dienst migrate (unter db) und die lange Form von depends_on für api. Die DB-URL ist länger als eine Zeile: In doppelten Anführungszeichen setzt YAML ein \ am Zeilenende ohne Leerzeichen fort.

  api:
    build: notes-api
    restart: unless-stopped
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY:?NOTES_API_KEY fehlt (.env)}
      NOTES_DB_URL: "postgres://notes:\
        ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}@db:5432/notes"
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"
    networks: [frontend, backend]
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully

  migrate:
    build: notes-api
    command: ["migrate"]
    restart: "no"
    environment:
      NOTES_DB_URL: "postgres://notes:\
        ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}@db:5432/notes"
    networks: [backend]
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      disable: true

command: ["migrate"] hängt sich an den ENTRYPOINT ["/notes-api"] des Images an. healthcheck: disable: true schaltet den Image-Healthcheck ab – ein Job, der nach einer Sekunde endet, braucht keinen.

docker compose down -v
docker compose up -d api
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'
docker compose logs migrate api
docker compose images --format json \
  | jq -r '.[] | "\(.ContainerName)  \(.Repository):\(.Tag)"'

Erwartet (gekürzt, IDs und Zeiten weichen ab):

 Image notes-migrate Built
 Container notes-db-1 Started
 Container notes-db-1 Waiting
 Container notes-db-1 Healthy
 Container notes-migrate-1 Started
 Container notes-migrate-1 Waiting
 Container notes-migrate-1 Exited
 Container notes-api-1 Started
SERVICE   STATUS
api       Up Less than a second (health: starting)
db        Up 3 seconds (healthy)
migrate   Exited (0) Less than a second ago
migrate-1  | time=… level=INFO msg="migration complete" table=notes
api-1      | time=… level=INFO msg="api key loaded" source=env
api-1      | time=… level=INFO msg="store ready" store=postgres
api-1      | time=… level=INFO msg=listening addr=:8080 version=dev pid=1
notes-api-1  notes-api:latest
notes-migrate-1  notes-migrate:latest
notes-db-1  postgres:18.6-alpine

Du hast nur api verlangt; Compose zieht db und migrate als Abhängigkeiten mit und hält die Reihenfolge ein. migrate bleibt als Exited (0) stehen, das ist sein Normalzustand. Das Image notes-migrate ist ein zweites Tag auf denselben Inhalt wie notes-api – der Build kam komplett aus dem Cache.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Healthcheck aus dem Image

worker und web sollen erst starten, wenn api gesund ist. web bekommt einen eigenen Healthcheck mit dem BusyBox-wget aus node:26-alpine:

  worker:
    # … build, environment, networks wie an Tag 4 …
    restart: unless-stopped
    depends_on:
      api:
        condition: service_healthy

  web:
    # … build, environment, ports, networks wie an Tag 4 …
    restart: unless-stopped
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
      interval: 10s
      timeout: 2s
      start_period: 10s
      start_interval: 1s

api hat in compose.yaml keinen healthcheck:. Woher kommt ihr „healthy”?

docker compose config --format json | jq '.services.api.healthcheck'
docker inspect -f '{{json .Config.Healthcheck.Test}} {{.Config.Healthcheck.Interval}}' \
  notes-api-1

Erwartet:

null
["CMD","/notes-api","healthcheck"] 10s

Der HEALTHCHECK aus dem Dockerfile gilt, solange Compose ihn nicht überschreibt. Ein healthcheck: im Dienst würde einzelne Werte ersetzen, disable: true ihn abschalten (wie bei migrate). Jetzt der ganze Stack:

docker compose up -d --wait; echo "Exit: $?"
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Tag 5 startet in der richtigen Reihenfolge"}'; echo
sleep 11; docker compose logs worker | tail -2

Erwartet (gekürzt, IDs und Zeiten weichen ab):

 Container notes-db-1 Healthy
 Container notes-migrate-1 Started
 Container notes-migrate-1 Exited
 Container notes-api-1 Healthy
 Container notes-web-1 Started
 Container notes-worker-1 Started
 Container notes-worker-1 Healthy
 Container notes-web-1 Healthy
Exit: 0
SERVICE   STATUS
api       Up 10 seconds (healthy)
db        Up 12 seconds (healthy)
migrate   Exited (0) 2 seconds ago
web       Up 1 second (healthy)
worker    Up 1 second
{"id":"084ea6e5-…","text":"Tag 5 startet in der richtigen Reihenfolge"}
worker-1  | summary: 0 notes, 0 words
worker-1  | summary: 1 notes, 7 words

Zwei Details: migrate lief bei diesem up noch einmal – jedes up startet den beendeten Job erneut, deshalb muss eine Migration idempotent sein. Und worker meldet „Healthy”, obwohl er keinen Healthcheck hat: Für --wait zählt dann „läuft”.

Fortschritt speichern? Kostenlos registrieren

Drill 6: restart-Policies

restart: startet neu, wenn der Container endet …
"no" (Standard) nie
on-failure[:N] nur mit Exit-Code ungleich 0, optional höchstens N-mal
unless-stopped immer, außer du hast ihn selbst gestoppt
always immer; selbst gestoppte auch nach einem Neustart des Docker-Daemons

"no" braucht Anführungszeichen, sonst liest YAML es als false. Was zählt als „selbst gestoppt”?

docker compose kill api
sleep 3
docker compose ps -a api --format 'table {{.Service}}\t{{.Status}}'
docker compose up -d --wait >/dev/null 2>&1
docker compose exec web kill 1
sleep 3
docker compose ps web --format 'table {{.Service}}\t{{.Status}}'
docker inspect -f 'RestartCount={{.RestartCount}}' notes-web-1

Erwartet (gekürzt):

 Container notes-api-1 Killed
SERVICE   STATUS
api       Exited (137) 3 seconds ago
SERVICE   STATUS
web       Up 2 seconds (healthy)
RestartCount=1

kill, stop und down sind Absicht – kein Neustart. Endet der Prozess von innen (hier SIGTERM an Node, Exit 0), startet Docker ihn neu. Spannender: api ohne Datenbank.

docker compose stop db
docker compose restart api
sleep 8
docker compose ps -a api db --format 'table {{.Service}}\t{{.Status}}'
docker inspect -f 'RestartCount={{.RestartCount}}' notes-api-1
docker compose start db
sleep 15
docker compose ps -a api db --format 'table {{.Service}}\t{{.Status}}'

Erwartet (gekürzt, Zahlen weichen ab):

 Container notes-db-1 Stopped
 Container notes-api-1 Started
SERVICE   STATUS
api       Restarting (1) 2 seconds ago
db        Exited (0) 8 seconds ago
RestartCount=6
 Container notes-db-1 Started
SERVICE   STATUS
api       Up 14 seconds (healthy)
db        Up 15 seconds (healthy)

restart fragt nicht nach Abhängigkeiten. api scheitert, Docker startet sie mit wachsender Pause neu, bis db zurück ist – die Policy rettet, was depends_on nicht abdeckt, etwa nach einem Neustart der VM.

Achtung: Ein unhealthy Container wird nicht neu gestartet. Healthchecks steuern in Compose nur Abhängigkeiten und --wait, nicht die restart-Policy.

Fortschritt speichern? Kostenlos registrieren

Drill 7: depends_on mit restart und required

Zwei weitere Felder der langen Form. restart: true startet einen Dienst neu, wenn Compose seine Abhängigkeit neu startet oder ersetzt. Trag es vorübergehend bei api ein:

    depends_on:
      db:
        condition: service_healthy
        restart: true
docker compose up -d --wait >/dev/null 2>&1
docker inspect -f '{{.State.StartedAt}}' notes-api-1
docker compose restart db
docker inspect -f '{{.State.StartedAt}}' notes-api-1

Erwartet (gekürzt, Zeiten weichen ab):

2026-10-29T20:44:11.46…Z
 Container notes-db-1 Restarting
 Container notes-db-1 Started
 Container notes-db-1 Waiting
 Container notes-db-1 Healthy
 Container notes-api-1 Restarting
 Container notes-api-1 Started
2026-10-29T20:44:46.59…Z

Ohne restart: true bleibt der Startzeitpunkt von api gleich (probier es). Für notes-api ist das unnötig – database/sql baut die Verbindungen von selbst neu auf –, für Anwendungen mit fester Verbindung beim Start ist es Gold wert. Nimm die Zeile wieder heraus.

required: false macht eine Abhängigkeit optional. Das zeigt sich, wenn der andere Dienst gar nicht aktiv ist – zum Beispiel durch ein Profil (Tag 7). Ergänze vorübergehend einen Dienst tracer und eine Abhängigkeit bei worker:

  worker:
    # …
    depends_on:
      api:
        condition: service_healthy
      tracer:
        condition: service_started

  tracer:
    image: postgres:18.6-alpine
    profiles: [debug]
    command: ["sleep", "infinity"]
docker compose up -d --wait; echo "Exit: $?"

Erwartet:

service "worker" depends on undefined service "tracer": invalid compose project
Exit: 1

Mit required: false unter tracer: läuft dasselbe up mit Exit 0, und worker startet ohne tracer. Entferne tracer und die Abhängigkeit wieder und prüfe mit docker compose config -q.

Fortschritt speichern? Kostenlos registrieren

Drill 8: up --wait und --wait-timeout

docker compose up --help | grep -E -- '--wait'
docker compose down -v
docker compose up -d --wait --wait-timeout 1 db; echo "Exit: $?"
docker compose ps -a db --format 'table {{.Service}}\t{{.Status}}'

Erwartet (gekürzt):

      --wait                         Wait for services to be
      --wait-timeout int             Maximum duration in seconds to wait
 Container notes-db-1 Started
 Container notes-db-1 Waiting
application not healthy after 1s
Exit: 1
SERVICE   STATUS
db        Up 1 second (healthy)

Der Timeout bricht nur das Warten ab, der Container läuft weiter und wird kurz darauf gesund. Endet ein Container beim Warten, scheitert --wait sofort:

docker compose up -d --wait >/dev/null 2>&1
docker compose stop db
docker compose up -d --wait --wait-timeout 15 --no-deps --force-recreate api
echo "Exit: $?"
docker compose ps -a api db --format 'table {{.Service}}\t{{.Status}}'
docker compose up -d --wait >/dev/null 2>&1; echo "Exit: $?"

Erwartet (gekürzt):

 Container notes-db-1 Stopped
 Container notes-api-1 Recreated
 Container notes-api-1 Started
 Container notes-api-1 Waiting
container notes-api-1 is unhealthy
Exit: 1
SERVICE   STATUS
api       Restarting (1) Less than a second ago
db        Exited (0) 1 second ago
Exit: 0

--no-deps startet api ohne db, --force-recreate erzwingt einen frischen Container. Ab jetzt startest du den Stack immer mit docker compose up -d --wait: Exit 0 heißt „alle Dienste gesund bzw. Jobs fertig”, in Skripten und in CI (Tag 13) genau die Bedingung, die du brauchst.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Der Stack läuft (docker compose up -d --wait). Den vollständigen Stand findest du in code/tag05/notes/compose.yaml. Gesundheit und Status aller Dienste:

cd ~/compose-lab/tag05
docker compose ps -a --format '{{.Service}} {{.Status}}'

Erwartet (Zeiten weichen ab): db, api und web healthy, migrate mit Exit 0 beendet.

api Up 4 seconds (healthy)
db Up 11 seconds (healthy)
migrate Exited (0) 5 seconds ago
web Up 2 seconds (healthy)
worker Up 2 seconds

api wartet auf migrate:

docker compose config --format json | jq '.services.api.depends_on.migrate'

Erwartet:

{
  "condition": "service_completed_successfully",
  "required": true
}

Der db-Healthcheck fragt über TCP:

docker compose config --format json | jq -c '.services.db.healthcheck.test'

Erwartet:

["CMD","pg_isready","-h","127.0.0.1","-U","notes","-d","notes"]

GET /notes liefert 200:

curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/notes

Erwartet:

200

Challenge

Starte den laufenden Stack einmal mit einem falschen Datenbank-Passwort neu, ohne eine Datei zu ändern. Welcher Dienst scheitert, was melden up --wait und der Exit-Code, und welche Dienste laufen danach noch? Stell anschließend den gesunden Stand wieder her.

Hinweis: Eine Variable aus der Shell schlägt die .env (Tag 4), und Postgres liest POSTGRES_PASSWORD nur bei einem leeren Volume.

Lösung

cd ~/compose-lab/tag05
POSTGRES_PASSWORD=lab-db-pw-456 docker compose up -d --wait; echo "Exit: $?"
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'
docker compose logs --no-log-prefix migrate | tail -1 | grep -o 'password auth.*28P01)'

Erwartet (gekürzt, Zeiten weichen ab):

 Container notes-db-1 Recreated
 Container notes-migrate-1 Recreated
 Container notes-api-1 Recreated
 Container notes-db-1 Healthy
 Container notes-migrate-1 Started
 Container notes-migrate-1 Error service "migrate" didn't complete successfully: exit 1
service "migrate" didn't complete successfully: exit 1
Exit: 1
SERVICE   STATUS
api       Created
db        Up 2 seconds (healthy)
migrate   Exited (1) Less than a second ago
web       Up 7 seconds (healthy)
worker    Up 7 seconds
password authentication failed for user \"notes\" (SQLSTATE 28P01)

Die geänderte Umgebung ließ Compose db, migrate und api neu erzeugen. Postgres ignorierte das neue Passwort (Volume vorhanden), migrate scheiterte an der Anmeldung, und api blieb im Zustand Created – sie wurde nie gestartet. worker und web liefen weiter, ihre Konfiguration hatte sich nicht geändert. In manchen Läufen erscheint zusätzlich „dependency db failed to start” – irreführend, maßgeblich ist die Zeile über migrate. Reparatur:

docker compose up -d --wait; echo "Exit: $?"
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'

Erwartet (gekürzt):

 Container notes-migrate-1 Exited
 Container notes-api-1 Healthy
Exit: 0
SERVICE   STATUS
api       Up 2 seconds (healthy)
db        Up 4 seconds (healthy)
migrate   Exited (0) 2 seconds ago
web       Up 12 seconds (healthy)
worker    Up 12 seconds

Zum Abschluss des Tages: docker compose down (ohne -v, die Daten bleiben).

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • depends_on wirkt nur, wenn Compose startet. Nach einem Datenbank-Failover oder in Kubernetes hilft es nicht: Dienste brauchen trotzdem Wiederholungen mit Backoff.
  • Kubernetes trennt, was Compose in einem Healthcheck bündelt: Readiness (Traffic ja oder nein), Liveness (Neustart) und Startup-Probes. Docker startet unhealthy Container nicht neu; „Autoheal”-Container brauchen dafür den Docker-Socket – vermeiden (Tag 9).
  • Migrationen laufen in Pipelines meist als eigener Schritt oder Kubernetes-Job (Helm-Hook). Mit mehreren Instanzen braucht die Migration eine Sperre, etwa ein Postgres-Advisory-Lock, damit sie nicht parallel läuft.
  • up --wait mit --wait-timeout ist das Gate für Deployments (Tag 14) und CI (Tag 13): kein sleep 30 mehr in Skripten.
  • Healthchecks kosten: Bei vielen Containern und kurzem interval erzeugen sie spürbar Last. start_interval hält den Start schnell, ohne das Intervall im Betrieb zu senken.