Stand: 05.10.2026

Ein Docker Healthcheck prüft nicht nur, ob ein Container läuft, sondern ob er seine Aufgabe noch erfüllen kann. In Docker Compose kombinierst Du ihn mit depends_on und service_healthy, damit abhängige Dienste erst starten, wenn beispielsweise die Datenbank wirklich bereit ist.

Auf einen Blick

  • Ein Docker Healthcheck ergänzt den Status eines Containers um starting, healthy oder unhealthy.
  • Der Prüf-Befehl muss im Container verfügbar sein und genau die benötigte Funktion prüfen.
  • service_healthy sorgt in Compose beim Start für die richtige Reihenfolge.
  • Mit docker inspect findest Du die gespeicherte Ausgabe einer fehlgeschlagenen Prüfung.

Ein Docker Healthcheck ist eine regelmäßig ausgeführte Prüfung im Container. Er beantwortet damit eine andere Frage als der Prozessstatus: Läuft der Prozess noch, oder kann der Dienst tatsächlich Anfragen bearbeiten? Das ist besonders wichtig, wenn eine Anwendung von einer Datenbank, einem Cache oder einer HTTP-Schnittstelle abhängt.

Warum reicht „Container läuft“ nicht aus?

Ein laufender Container ist noch nicht zwingend einsatzbereit. Laut der Dockerfile-Referenz kann ein Healthcheck auch Fälle erkennen, in denen ein Webserver zwar noch läuft, aber keine neuen Verbindungen mehr bedienen kann. Deshalb liefert Docker zusätzlich zum normalen Status einen Gesundheitsstatus.

Nach dem Start lautet dieser Status zunächst starting. Besteht eine Prüfung, wird der Container healthy. Erst nach der festgelegten Zahl aufeinanderfolgender Fehler wechselt er zu unhealthy. Damit hast Du eine klarere Grundlage für Monitoring und für die Startreihenfolge in Compose.

Für den Einstieg in mehrteilige Stacks hilft auch unser Artikel zu Docker Compose Grundlagen. Ein Healthcheck ersetzt allerdings weder Backups noch eine sichere Image-Auswahl; beides gehört weiter zu den Docker-Security-Maßnahmen.

Docker Healthcheck: Welche Werte sind wichtig?

Die Prüfung besteht aus einem Befehl und aus Zeitwerten. Docker dokumentiert dafür test, interval, timeout, retries und start_period. Der Befehl muss mit Exit-Code 0 enden, wenn der Dienst bereit ist; Exit-Code 1 bedeutet dagegen fehlerhaft. Exit-Code 2 ist reserviert und sollte nicht verwendet werden.

FeldZweck
testDer Befehl, mit dem Docker den Dienst im Container prüft.
intervalAbstand zwischen zwei Prüfungen.
timeoutMaximale Dauer einer einzelnen Prüfung.
retriesAnzahl aufeinanderfolgender Fehler bis unhealthy.
start_periodSchonzeit für die Initialisierung; Fehler zählen dort zunächst nicht.

Wähle diese Werte passend zum Dienst statt sie pauschal zu übernehmen. Eine Datenbank braucht nach einem Neustart oft mehr Zeit als ein kleiner HTTP-Dienst. Deshalb verhindert ein sinnvoller start_period, dass ein normaler Start als Ausfall gewertet wird. Die Docker-Dokumentation beschreibt außerdem: Läuft eine Prüfung länger als timeout, gilt sie als fehlgeschlagen.

Wie richtest Du einen Docker Healthcheck in Compose ein?

Am einfachsten hinterlegst Du den Docker Healthcheck direkt beim Dienst in der Compose-Datei. Das folgende Muster folgt dem Beispiel aus der offiziellen Compose-Dokumentation zur Startreihenfolge und prüft PostgreSQL mit dem dafür vorgesehenen Werkzeug pg_isready.

services:
  app:
    image: example/app:latest
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 10s
      retries: 5
      start_period: 30s

Ersetze example/app:latest durch Dein eigenes Image und passe den Datenbankteil an Deine bestehende Konfiguration an. Wichtig ist das doppelte Dollarzeichen: In einer Compose-Datei verhindert es, dass Compose die Variable schon beim Einlesen ersetzt. Der Befehl soll die Variablen erst im Container auswerten.

Starte oder aktualisiere den Stack anschließend mit:

docker compose up -d

Die Einstellung condition: service_healthy ist der entscheidende Teil für Abhängigkeiten. Compose wartet laut Dokumentation sonst nur darauf, dass ein Container läuft, nicht darauf, dass er bereit ist. Mit der Bedingung startet app daher erst nach einer erfolgreichen Datenbankprüfung.

Was prüft ein guter Docker Healthcheck?

Ein guter Docker Healthcheck prüft die kleinste Funktion, die für die nächste Abhängigkeit wirklich notwendig ist. Bei PostgreSQL ist das eine erfolgreiche Bereitschaftsabfrage. Bei einem HTTP-Dienst kann eine lokale Statusroute sinnvoll sein, sofern der verwendete Befehl im Image vorhanden ist. Prüfe nicht blind eine externe Website: Dann kann ein fremder Netzausfall Deinen Container fälschlich als krank markieren.

Außerdem sollte die Prüfung schnell und ohne Seiteneffekte laufen. Sie darf zum Beispiel keine Daten schreiben, keine Migration starten und keine teure Komplettabfrage auslösen. Dadurch bleibt die Aussage klar: Der Dienst kann seine Kernaufgabe erfüllen. Wenn Du Images selbst baust, gehören solche Entscheidungen zu den Dockerfile Best Practices.

Wie prüfst Du den Status und findest Fehler?

Sieh zunächst den Zustand der Services an:

docker compose ps

Für die Details eines bestimmten Containers verwendest Du anschließend:

docker inspect <container-name>

Docker speichert laut Dockerfile-Referenz die Ausgabe von Standardausgabe und Standardfehler einer fehlgeschlagenen Prüfung im Health-Status; sie ist über docker inspect abrufbar. Das macht die Fehlersuche deutlich konkreter als ein reiner Statuswechsel. Achte etwa auf einen nicht vorhandenen Befehl, einen falschen Port oder auf eine Datenbank, die länger initialisiert als der eingestellte Zeitraum.

Typische Fehler bei Docker Healthchecks

Der Prüf-Befehl existiert nicht im Image. Minimal-Images enthalten oft weder curl noch eine Shell. Verwende daher ein Werkzeug, das im Image vorhanden ist, oder baue bewusst ein passendes Prüfwerkzeug ein. Die Compose-Referenz zeigt als HTTP-Beispiel ["CMD", "curl", "-f", "http://localhost"]; das funktioniert nur, wenn curl tatsächlich installiert ist.

Die Anwendung startet vor ihrer Datenbank. depends_on allein regelt die Reihenfolge der Container, aber nicht die Bereitschaft. Ergänze deshalb den Healthcheck beim abhängigen Dienst und condition: service_healthy beim Verbraucher.

Die Zeitwerte passen nicht zum Startverhalten. Erhöhe zuerst die Schonzeit für erwartete Initialisierung. Mehr Wiederholungen allein lösen kein Timing-Problem, wenn der Check zu früh beginnt. Dokumentiere zudem, warum Du einen Wert gewählt hast, damit spätere Änderungen nachvollziehbar bleiben.

Fazit

Ein Docker Healthcheck macht den tatsächlichen Zustand eines Dienstes sichtbar und verbessert die Startreihenfolge in Compose. Beginne mit einer kleinen, lokalen Bereitschaftsprüfung und kombiniere sie bei Abhängigkeiten mit service_healthy. Prüfe nach jeder Änderung den Status und die gespeicherte Diagnoseausgabe, statt Zeitwerte nur zu raten.

Quellen

Häufige Fragen

Was ist ein Docker Healthcheck?

Ein Docker Healthcheck führt im Container regelmäßig einen definierten Befehl aus. Docker ergänzt den normalen Containerstatus dadurch um starting, healthy oder unhealthy.

Startet Docker Compose nach einem Healthcheck automatisch den abhängigen Dienst?

Mit depends_on und condition: service_healthy wartet Compose beim Start, bis die Abhängigkeit healthy meldet. Ohne diese Bedingung wartet Compose nur darauf, dass der Container läuft.

Wie sehe ich, warum ein Docker Healthcheck fehlschlägt?

Mit docker inspect für den betreffenden Container kannst Du den Health-Status und die von Docker gespeicherte Ausgabe der Prüfung einsehen.

Brauche ich curl für einen Docker Healthcheck?

Nein. Der Test kann jedes im Container verfügbare Werkzeug nutzen, das mit Exit-Code 0 Erfolg und mit Exit-Code 1 einen Fehler meldet. Bei Datenbanken ist oft ein mitgeliefertes Bereitschaftswerkzeug geeigneter.

Post Views: 5