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_onin 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_healthyundservice_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
migratean. api startet erst, wenn er mit Exit 0 endet. restart:regelt, was nach einem Absturz passiert;up --waitmeldet 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 -1Erwartet (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: truecommand: ["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: 1sapi 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-1Erwartet:
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 -2Erwartet (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-1Erwartet (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
unhealthyContainer 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: truedocker 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-1Erwartet (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/notesErwartet:
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_onwirkt 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
unhealthyContainer 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 --waitmit--wait-timeoutist das Gate für Deployments (Tag 14) und CI (Tag 13): keinsleep 30mehr in Skripten.- Healthchecks kosten: Bei vielen Containern und kurzem
intervalerzeugen sie spürbar Last.start_intervalhält den Start schnell, ohne das Intervall im Betrieb zu senken.