Stand: 26.10.2026

Ein Docker Healthcheck zeigt, ob ein Container seine Aufgabe tatsächlich erfüllen kann, nicht nur ob sein Hauptprozess noch läuft. In Docker Compose kannst Du diesen Status für eine verlässliche Startreihenfolge nutzen. So richtest Du einen passenden Test ein, liest Fehler aus und vermeidest typische Fehlalarme.

Auf einen Blick

  • Ein Docker Healthcheck ergänzt den Laufzeitstatus um starting, healthy oder unhealthy.
  • Der Test läuft im Container und muss dort vorhandene Werkzeuge verwenden.
  • depends_on mit condition: service_healthy wartet beim Start auf eine gesunde Abhängigkeit.
  • Prüfe den Status und die letzte Testausgabe mit docker inspect, statt nur Zeitwerte zu erhöhen.

Was prüft ein Docker Healthcheck genau?

Ein Docker Healthcheck führt regelmäßig einen Befehl im Container aus. Ein Rückgabecode von 0 bedeutet erfolgreich; ein Fehlercode markiert den einzelnen Test als fehlgeschlagen. Nach mehreren aufeinanderfolgenden Fehlern wechselt der Gesundheitsstatus auf unhealthy. Der Container kann dabei weiterlaufen.

Das ist der wichtige Unterschied zum Status running. Ein Webserverprozess kann laufen, obwohl die Anwendung nicht antwortet. Ebenso kann eine Datenbank gestartet sein, aber noch keine Verbindungen annehmen. Ein Healthcheck schafft hier eine zusätzliche, klar definierte Aussage.

Lege vor dem Test fest, welche Funktion wirklich bereit sein muss. Für PostgreSQL ist das oft eine erfolgreiche Bereitschaftsabfrage. Für eine Webanwendung kann eine lokale Statusroute passen. Prüfe jedoch nicht blind eine fremde Internetseite: Ein externer Netzausfall würde sonst Deinen eigenen Dienst fälschlich als krank bewerten.

Welche Einstellungen gehören in den Docker Healthcheck?

Docker und Compose verwenden für Healthchecks dieselben Grundwerte. Passe sie an die reale Startzeit und Last Deines Dienstes an. Ein pauschaler Wert für jeden Container führt entweder zu Fehlalarmen oder zu einer langsamen Erkennung.

FeldBedeutungPraktischer Hinweis
testBefehl oder Befehlsliste für die PrüfungEr muss im Image verfügbar sein und keine Daten verändern.
intervalAbstand zwischen regulären PrüfungenWähle ihn passend dazu, wie schnell Du einen Ausfall erkennen musst.
timeoutMaximale Dauer eines TestsEin festhängender Test zählt nach Ablauf als Fehler.
retriesFehler in Folge bis unhealthyGlättet kurze, erwartbare Störungen.
start_periodSchonzeit beim StartNutze sie für erwartete Initialisierung, etwa Datenbankmigrationen.
start_intervalPrüfabstand während der StartphaseDie aktuelle Compose-Referenz führt diese Option zusätzlich auf; prüfe mit docker compose config, ob Deine Installation sie akzeptiert.

Die Dockerfile-Referenz nennt als Standardwerte 30 Sekunden für interval und timeout, null Sekunden für start_period, fünf Sekunden für start_interval und drei Wiederholungen. Übernimm diese Werte nicht automatisch. Messe lieber, wie lange Dein Dienst nach einem normalen Neustart benötigt.

Wie richtest Du einen Docker Healthcheck in Compose ein?

Der folgende Ausschnitt zeigt eine Anwendung mit PostgreSQL. pg_isready gehört zum PostgreSQL-Image und prüft die Bereitschaft, ohne Daten zu schreiben. Die Anwendung wartet beim ersten Start, bis die Datenbank als gesund gilt.

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

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

Das doppelte Dollarzeichen ist absichtlich gesetzt. Compose gibt dadurch die Variable an die Shell im Container weiter, statt sie beim Einlesen der Compose-Datei zu ersetzen. Falls Dein Check keine Shell, Pipe oder Variable braucht, ist die Listenform mit CMD oft einfacher.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 3s
  retries: 3

Dieses HTTP-Beispiel funktioniert nur, wenn curl im Image installiert ist und die Route tatsächlich ohne Anmeldung erreichbar sein soll. Minimal-Images enthalten häufig weder curl noch eine Shell. Baue ein benötigtes Werkzeug bewusst ein oder nutze einen bereits mitgelieferten Prüfclient. Wie Du Images nachvollziehbar und schlank hältst, erklärt der Beitrag zu Dockerfile Best Practices.

Warum reicht depends_on allein nicht?

depends_on ordnet die Erstellung und den Start von Diensten. Ohne Bedingung wartet Compose aber nicht darauf, dass eine Datenbank oder ein API-Dienst bereits Anfragen verarbeiten kann. Genau dafür setzt Du bei der Abhängigkeit einen Healthcheck und beim Verbraucher condition: service_healthy.

Starte den Stack anschließend wie gewohnt. Prüfe zuerst die aufgelöste Konfiguration, besonders wenn Du Variablen oder Erweiterungen verwendest.

docker compose config
docker compose up -d
docker compose ps

Die Wartebedingung hilft beim expliziten Start über Compose. Sie ersetzt kein Überwachungssystem und keine automatische Wiederherstellung. Bei einem späteren Ausfall musst Du das gewünschte Verhalten über die Anwendung, eine Restart-Strategie und Monitoring planen. Für den Einstieg in Service-Dateien und Befehle hilft auch unsere Docker-Compose-Anleitung.

Wie prüfst Du Status und Fehlerausgabe?

Sieh zunächst die Services an. Der Gesundheitsstatus erscheint bei einem konfigurierten Check neben dem Containerstatus.

docker compose ps

Für die vollständige Diagnose frage den Health-Bereich eines bestimmten Containers ab. Er enthält Status, Start- und Endzeit sowie die letzte gespeicherte Ausgabe.

docker inspect --format '{{json .State.Health}}' <container-name>

Ist der Bereich leer, wurde für diesen Container kein Healthcheck gesetzt oder er wurde deaktiviert. Bei unhealthy lies zuerst die Testausgabe: Häufig fehlen ein Befehl, der richtige lokale Port oder Berechtigungen. Prüfe danach den Dienst selbst und seine Logs. Erhöhe nicht sofort retries; sonst verdeckst Du nur die Ursache.

Wann sollte ein Healthcheck bewusst einfach bleiben?

Ein Healthcheck ist kein vollständiger End-to-End-Test. Sein Ziel ist eine schnelle Entscheidung, ob der Container für seine unmittelbare Aufgabe bereit ist. Deshalb sollte er lokal laufen, wenig Ressourcen verbrauchen und bei Erfolg oder Fehler eindeutig enden. Eine Anmeldung über mehrere Fremdsysteme gehört eher in einen separaten Monitoring-Check.

Teste den Befehl zunächst interaktiv im gestarteten Container. Erst wenn er dort zuverlässig einen passenden Rückgabecode liefert, übernimmst Du ihn in die Compose-Datei. Danach prüfst Du die aufgelöste Konfiguration mit docker compose config und führst einen Neustart kontrolliert aus. Dieser Ablauf verhindert, dass ein YAML- oder Variablenfehler als Anwendungsproblem erscheint.

docker compose exec db pg_isready -U app -d app
docker compose config
docker compose up -d
docker compose ps

Ersetze den Beispielbefehl durch den Check Deines Dienstes. Nutze dabei keine Zugangsdaten in der Compose-Datei, die Du nicht ohnehin für den Dienst benötigst. Wenn eine Anwendung bereits einen dokumentierten Readiness-Endpunkt anbietet, ist dieser meist die bessere Grundlage als ein selbst gebauter Ersatz.

Welche Fehler solltest Du vermeiden?

Der Test prüft nur einen offenen Port. Ein offener Port beweist nicht, dass die Anwendung ihre Kernfunktion ausführt. Eine kleine, lokale Bereitschaftsprüfung liefert mehr Aussagekraft. Sie sollte schnell sein und keine Seiteneffekte haben.

Der Test schreibt Daten oder löst teure Arbeit aus. Healthchecks laufen wiederholt. Deshalb gehören keine Migration, kein Backup und keine Volltextsuche hinein. Für Sicherungen von Volumes ist ein separater Prozess nötig, etwa wie in der Anleitung zu Restic mit Docker.

Die Startphase ist zu kurz. Wenn ein Dienst beim Kaltstart erwartbar länger braucht, verwende start_period. Beobachte danach einen echten Neustart. So unterscheidest Du eine normale Initialisierung von einem dauerhaften Fehler.

Ein vorhandener Image-Healthcheck wird versehentlich überschrieben. Prüfe vor einer eigenen Definition die Image-Dokumentation und docker inspect. Compose kann einen vorhandenen Check überschreiben oder mit disable: true abschalten. Deaktiviere ihn nur, wenn Du einen nachvollziehbaren Ersatz hast.

Fazit

Ein Docker Healthcheck ergänzt den Prozessstatus um einen echten Bereitschaftstest. Wähle eine kleine lokale Prüfung, die im Image funktioniert, und nutze bei Compose-Abhängigkeiten service_healthy. Kontrolliere nach jeder Änderung Status und Testausgabe. Dann erkennst Du nicht nur, dass ein Container läuft, sondern ob der Dienst nutzbar ist.

Quellen

Häufige Fragen

Was ist ein Docker Healthcheck?

Ein Docker Healthcheck führt regelmäßig einen definierten Befehl im Container aus. Er ergänzt den Containerstatus um starting, healthy oder unhealthy und zeigt damit mehr als running allein.

Startet Docker Compose abhängige Dienste erst nach dem Healthcheck?

Mit depends_on und condition: service_healthy wartet Compose beim Start, bis die markierte Abhängigkeit eine erfolgreiche Healthcheck-Prüfung meldet.

Wie finde ich den Fehler eines unhealthy Containers?

Nutze docker inspect –format '{{json .State.Health}}' mit dem Containernamen. Dort stehen Status und die gespeicherte Ausgabe der letzten Healthchecks.

Braucht ein Docker Healthcheck immer curl?

Nein. Der Test kann jedes im Container vorhandene Werkzeug verwenden. Für Datenbanken ist ein mitgelieferter Bereitschaftsclient oft passender als ein HTTP-Abruf.

Ersetzt ein Healthcheck Monitoring und Backups?

Nein. Er liefert einen Gesundheitsstatus für einen Container. Monitoring, Alarmierung, Restart-Verhalten und Backups brauchen weiterhin eigene, passende Konzepte.