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,healthyoderunhealthy. - Der Test läuft im Container und muss dort vorhandene Werkzeuge verwenden.
depends_onmitcondition: service_healthywartet 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.
| Feld | Bedeutung | Praktischer Hinweis |
|---|---|---|
test | Befehl oder Befehlsliste für die Prüfung | Er muss im Image verfügbar sein und keine Daten verändern. |
interval | Abstand zwischen regulären Prüfungen | Wähle ihn passend dazu, wie schnell Du einen Ausfall erkennen musst. |
timeout | Maximale Dauer eines Tests | Ein festhängender Test zählt nach Ablauf als Fehler. |
retries | Fehler in Folge bis unhealthy | Glättet kurze, erwartbare Störungen. |
start_period | Schonzeit beim Start | Nutze sie für erwartete Initialisierung, etwa Datenbankmigrationen. |
start_interval | Prüfabstand während der Startphase | Die 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
- Docker Docs: HEALTHCHECK in der Dockerfile-Referenz
- Docker Docs: Start- und Stopp-Reihenfolge in Compose
- Docker Docs: Compose-Referenz für healthcheck
Häufige Fragen
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.
Mit depends_on und condition: service_healthy wartet Compose beim Start, bis die markierte Abhängigkeit eine erfolgreiche Healthcheck-Prüfung meldet.
Nutze docker inspect –format '{{json .State.Health}}' mit dem Containernamen. Dort stehen Status und die gespeicherte Ausgabe der letzten Healthchecks.
Nein. Der Test kann jedes im Container vorhandene Werkzeug verwenden. Für Datenbanken ist ein mitgelieferter Bereitschaftsclient oft passender als ein HTTP-Abruf.
Nein. Er liefert einen Gesundheitsstatus für einen Container. Monitoring, Alarmierung, Restart-Verhalten und Backups brauchen weiterhin eigene, passende Konzepte.





2 Pingbacks