Docker Compose Healthchecks erklärt

docker compose ps zeigte bei jedem Container Up. Das Dashboard hinter einem davon lieferte seit vierzig Minuten 500er-Fehler, bevor es überhaupt jemandem auffiel — ein nachgelagerter Backup-Job versuchte immer wieder, darauf zuzugreifen, und scheiterte immer wieder, ohne dass Composes eigene Statuszeile jemals etwas davon verriet. Up stimmte die ganze Zeit. Es war trotzdem nutzlos.

Warum 'Up' nicht 'Healthy' bedeutet

Standardmäßig verfolgt Docker nur eine Sache: ob der Hauptprozess des Containers noch läuft. Laut der Compose-Datei-Referenz zu Healthchecks hat ein Container ohne healthcheck:-Block keinen weiteren Zustand — er läuft entweder oder er ist gestoppt, nichts dazwischen. Ein Prozess kann am Leben sein und trotzdem völlig kaputt: hängend bei einer Abhängigkeit, verklemmt in einem Deadlock, oder liefert bei jedem Request einen 500er, während seine Event-Loop technisch weiterdreht.

Diese Lücke erzeugt zwei Fehlerbilder:

• Still tot: Der Prozess lebt, aber die Anwendung darin ist in einen schlechten Zustand abgestürzt und beendet sich nie.
• Langsamer Start, fälschlich als tot gewertet: Ein Dienst wie ein Medien-Indexer oder eine JVM-Anwendung braucht reale Zeit, um nutzbar zu werden, und eine naive Prüfung markiert ihn als unhealthy, bevor er eine faire Chance hatte.

Ein healthcheck:-Block macht aus "Prozess läuft" ein "Anwendung antwortet tatsächlich" und gibt Compose (und allem, was von diesem Dienst abhängt) ein Signal, auf das reagiert werden kann.

Der healthcheck-Block, Feld für Feld

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

• test: der Befehl, den Compose im Container ausführt. CMD-SHELL führt ihn über die Shell des Containers aus; ein reines CMD-Array überspringt die Shell und vermeidet Überraschungen beim Quoting.
• interval: wie oft die Prüfung läuft, sobald der Container den start_period hinter sich hat.
• timeout: wie lange eine einzelne Prüfung laufen darf, bevor sie als Fehlschlag zählt.
• retries: aufeinanderfolgende Fehlschläge, bevor Compose den Container als unhealthy markiert.
• start_period: ein Gnadenfenster, in dem Fehlschläge nicht gegen retries zählen — nur ein Erfolg innerhalb dieses Fensters kann es vorzeitig beenden.

Abstimmung für echte Dienste (keine Spielzeug-Defaults)

Jedes Healthcheck-Tutorial zeigt das obige Postgres-Beispiel und hört dort auf. Die Werte, die tatsächlich zählen, sind die, die sich pro Dienst unterscheiden — eine schnell fehlschlagende API und ein langsam startender Medien-Indexer sollten nicht denselben start_period teilen. Das sind die Werte, die ich für drei Dienste auf meinem eigenen Proxmox-Homelab einsetze, ermittelt, indem ich die reale Bootzeit jedes Dienstes in docker compose logs -f beobachtet habe, statt einen Default zu kopieren:

Dienst	Boot-Profil	interval	timeout	retries	start_period	Warum
Postgres (db)	Schnell, berechenbar	5s	3s	5	10s	WAL-Recovery ist bei einem sauberen Shutdown selten und kurz; ein kurzer start_period erkennt einen wirklich kaputten Container schnell.
Interne REST-API	Schnell, hängt aber von db ab	10s	5s	3	15s	Etwas längerer start_period, um die eigene DB-Verbindungs-Retry-Schleife der API beim Kaltstart abzufedern.
Jellyfin (Medien-Indexer)	Langsam — Bibliotheksscan beim ersten Start	30s	10s	3	120s	Ein kalter Bibliotheksscan auf einem großen Medien-Volume kann über zwei Minuten dauern; ein kurzer start_period hier erzeugt nur falsche unhealthy-Flaps.

Die start_period-Ermessensentscheidung

start_period ist das Feld, bei dem die meisten Healthchecks falschliegen, weil es als einziges eine Ermessensentscheidung ist statt etwas Konkretes zu messen. Setzen Sie es zu kurz, wird ein legitim langsam startender Dienst — der Medien-Indexer oben ist der klarste Fall — als unhealthy markiert, während er noch normale Erststart-Arbeit verrichtet, was dann alles blockiert, was mit condition: service_healthy darauf wartet. Setzen Sie es zu lang, sitzt ein Container, der wirklich in einer Crash-Loop feststeckt, minutenlang im Gnadenfenster, bevor Compose überhaupt meldet, dass etwas nicht stimmt.

Healthchecks mit depends_on: condition: service_healthy verdrahten

Ein Healthcheck allein ändert nur, was docker compose ps meldet. Der eigentliche Nutzen entsteht, wenn Sie ihn mit depends_on verbinden, damit ein abhängiger Dienst nicht startet, bevor die Abhängigkeit tatsächlich bereit ist — nicht nur gestartet:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

  api:
    image: my-api:latest
    depends_on:
      db:
        condition: service_healthy

Ohne condition: service_healthy wartet depends_on laut der Compose-Dokumentation zur Startreihenfolge nur darauf, dass der Container-Prozess von db startet — nicht darauf, dass Postgres die Recovery abschließt und Verbindungen annimmt. Mit dieser Bedingung startet api erst gar nicht, bevor pg_isready Erfolg meldet — genau die Lücke, die dazu führt, dass eine erste Migration oder eine erste Abfrage gegen eine Datenbank fehlschlägt, die Sekunden zuvor technisch "gestartet" war.

Was passiert, wenn ein Container unhealthy wird

Wenn Compose einen Container als unhealthy markiert, startet er ihn nicht automatisch neu — Healthchecks und Restart-Policies sind zwei getrennte Mechanismen. Einen unhealthy-Container diagnostizieren Sie mit:

docker compose ps
docker inspect --format='{{json .State.Health}}' <container> | python3 -m json.tool

Der zweite Befehl gibt die tatsächliche Fehlerausgabe der letzten Prüfversuche aus, was fast immer schneller ist, als allein aus den Logs zu raten. Damit Compose sich tatsächlich vom unhealthy-Zustand erholt, kombinieren Sie den Healthcheck mit einer restart:-Policy — welche Policy zu welchem Fehlerbild passt, behandelt unser Leitfaden zu Docker-Compose-Restart-Policies; ein Healthcheck ohne dahinterliegende Restart-Policy erzeugt nur ein korrektes, aber dauerhaftes "kaputt"-Label.

Häufige Healthcheck-Fehler

• curl oder wget in einem minimalen Image verwenden, das diese nicht enthält — die Prüfung schlägt sofort mit "command not found" fehl, was in docker compose ps identisch zu einem echten Fehler aussieht. Installieren Sie das Tool bewusst, oder verwenden Sie eine sprachnative Prüfung (Postgres' eigenes pg_isready, ein kleines Skript, oder den bestehenden /health-Endpoint der App über ein Tool, das bereits im Image vorhanden ist).
• Prüfen, ob ein Port offen ist, statt ob die App bereit ist — ein Port kann TCP-Verbindungen annehmen, bevor die dahinterliegende Anwendung einen echten Request bedienen kann, besonders bei Diensten mit einer Aufwärmphase.
• retries zu niedrig für einen Dienst unter realer Last — ein Container, der unter Last kurz langsam ist (nicht kaputt), wird als unhealthy markiert und neu gestartet, was schlimmer ist als die vorübergehende Langsamkeit, auf die reagiert wurde. Wer noch entscheidet, welchen Netzwerkmodus ein stark ausgelasteter Dienst nutzen soll, findet in unserem network_mode: host-Erklärstück eine verwandte Quelle für Verbindungs-Flakiness.

FAQ

Wie prüfe ich, ob ein Docker-Container gesund ist?

Führen Sie docker compose ps aus, um die Statusspalte zu sehen, oder docker inspect --format='{{json .State.Health}}' <container> für die vollständige Historie der letzten Prüfversuche und deren Ausgabe.

Was ist start_period bei einem Docker-Healthcheck?

Ein Gnadenfenster nach dem Start des Containers, in dem fehlgeschlagene Prüfungen nicht gegen retries zählen. Nur eine erfolgreiche Prüfung innerhalb dieses Fensters kann es vorzeitig beenden. Es existiert, damit ein langsam startender Dienst nicht als unhealthy markiert wird, bevor er eine faire Chance hatte, den Start abzuschließen.

Warum zeigt mein Container "running", aber die App funktioniert nicht?

Weil Docker ohne einen healthcheck:-Block nur verfolgt, ob der Prozess des Containers lebt — nicht, ob die Anwendung darin tatsächlich korrekt antwortet. Fügen Sie einen Healthcheck hinzu, der echte Bereitschaft prüft, nicht nur, dass der Prozess existiert.

Startet Docker Compose unhealthy-Container automatisch neu?

Nein. Ein Healthcheck ändert nur den gemeldeten Status. Automatische Wiederherstellung erfordert eine separate restart:-Policy auf dem Dienst.

Wie funktioniert depends_on condition service_healthy in Docker Compose?

Ein abhängiger Dienst wartet damit, bis der Healthcheck der Abhängigkeit healthy meldet, bevor er startet — das schließt die Lücke des Standard-depends_on-Verhaltens, das nur darauf wartet, dass der Container-Prozess der Abhängigkeit startet.

Fazit

Up war nie ein Bereitschaftssignal — es ist ein Prozess-lebt-Signal, das nur so aussieht. Ein abgestimmter healthcheck:-Block, zugeschnitten auf die reale Bootzeit jedes Dienstes statt auf einen kopierten Default, macht aus dieser Lücke einen echten Status, auf den Compose (und alles, was vom Dienst abhängt) reagieren kann. Wer den Rest eines Multi-Service-Stacks darum herum aufbaut, findet in unserem Docker-Compose-Self-Hosting-Leitfaden die Grundlagen, die dieser Artikel voraussetzt.