Docker Healthcheck einrichten – Container überwachen

Ein Container läuft – aber tut er auch, was er soll? „Läuft“ heißt nicht automatisch „gesund“. Mit einem Healthcheck prüft Docker den tatsächlichen Zustand deiner Container regelmäßig selbst. In dieser Anleitung richtest du einen Docker Healthcheck im Dockerfile und in Compose ein und erfährst, wie du auf einen kranken Container reagierst.

Ein Docker Healthcheck ist der Unterschied zwischen „der Container läuft“ und „der Dienst funktioniert wirklich“. Ohne Healthcheck weiß Docker nur, ob der Hauptprozess noch lebt – nicht aber, ob deine Anwendung Anfragen beantwortet, die Datenbankverbindung steht oder ein Webserver einen 200er liefert. Genau diese Lücke schließt du mit einer Gesundheitsprüfung, die Docker in festen Intervallen selbst ausführt. In dieser Anleitung richtest du Healthchecks im Dockerfile und in Docker Compose ein, lernst die wichtigsten Parameter kennen und siehst, wie Orchestrierung und Neustart-Logik auf einen kranken Container reagieren.

Warum ein Healthcheck?

Ohne Healthcheck kennt Docker nur zwei Zustände: Der Hauptprozess läuft oder nicht. Eine App kann aber laufen und trotzdem nicht antworten – etwa weil die Datenbank hängt. Ein Healthcheck testet die echte Funktion und markiert den Container als healthy oder unhealthy.

Healthcheck in der docker-compose.yml

Am häufigsten definierst du den Healthcheck pro Dienst in Compose. Das Beispiel prüft alle 30 Sekunden, ob ein Webserver antwortet:

services:
  web:
    image: nginx:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

services:
  web:
    image: nginx:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

Die Compose-Grundlagen dazu findest du in Docker Compose installieren.

Healthcheck im Dockerfile

Alternativ verankerst du den Check direkt im Dockerfile, dann bringt jedes Image ihn mit:

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Den Status prüfen

Der aktuelle Gesundheitszustand erscheint direkt in der Container-Liste:

docker ps

docker ps

In der Spalte STATUS steht dann z. B. (healthy). Bleibt ein Container unhealthy, lohnt ein Blick in die Container-Logs.

Auf einen gesunden Dienst warten

Ein besonders praktischer Nebeneffekt: In Compose kannst du einen Dienst erst starten lassen, wenn ein anderer healthy ist. So wartet die App zuverlässig auf die Datenbank, statt bei einem Neustart ins Leere zu laufen:

services:
  app:
    image: meine-app:latest
    depends_on:
      datenbank:
        condition: service_healthy

services:
  app:
    image: meine-app:latest
    depends_on:
      datenbank:
        condition: service_healthy

Die Healthcheck-Parameter im Detail

Ein Healthcheck ist mehr als nur ein Test-Befehl. Über mehrere Optionen steuerst du, wie oft geprüft wird, wie lange ein Test dauern darf und ab wann Docker einen Container als unhealthy markiert. Die richtige Abstimmung verhindert Fehlalarme bei langsam startenden Diensten ebenso wie zu träges Reagieren auf echte Ausfälle.

Gerade start_period wird oft vergessen: Braucht deine Anwendung beim Start ein paar Sekunden, um Migrationen auszuführen oder einen Cache aufzubauen, würde sie sonst sofort als krank gelten. Mit einer großzügigen Anlaufzeit gibst du ihr Luft, ohne die spätere Überwachung abzuschwächen.

Womit du wirklich prüfen solltest

Ein guter Healthcheck testet den Dienst dort, wo ihn auch echte Nutzer erreichen. Ein simples curl -f http://localhost:8080/health auf einen dedizierten Health-Endpunkt sagt mehr aus als die Frage, ob der Prozess existiert. Der Endpunkt sollte leichtgewichtig sein und im Idealfall auch abhängige Ressourcen kurz antippen.

• Webdienste: HTTP-Anfrage auf einen /health-Pfad, der einen Statuscode 200 liefert.
• Datenbanken: ein Ping-Kommando wie pg_isready oder mysqladmin ping.
• Worker ohne Port: Prüfung einer Heartbeat-Datei oder eines internen Status-Kommandos.
• Vermeide zu schwere Tests – jeder Check läuft im festen Intervall und kostet Ressourcen.

Healthcheck in Orchestrierung und Neustarts

Der wahre Nutzen zeigt sich im Zusammenspiel mit Neustart-Regeln und Abhängigkeiten. In Docker Compose kannst du mit depends_on und der Bedingung service_healthy festlegen, dass ein Dienst erst startet, wenn seine Datenbank tatsächlich gesund ist – nicht nur gestartet. Das beseitigt eine ganze Klasse von Race-Conditions beim Hochfahren.

Kombinierst du den Healthcheck mit einer Compose-Restart-Policy wie restart: unless-stopped, sorgt Docker außerdem dafür, dass abgestürzte Container automatisch wieder hochkommen. In größeren Setups mit Swarm oder Kubernetes steuert der Gesundheitsstatus sogar das Ausrollen neuer Versionen und das Herausnehmen kranker Instanzen aus dem Load Balancer.

Für den laufenden Betrieb lohnt es sich, den Status aktiv zu beobachten. Mit docker ps siehst du in der Spalte STATUS direkt Werte wie (healthy) oder (unhealthy). Möchtest du auf Zustandswechsel reagieren, liefert docker events --filter event=health_status einen Live-Stream, den du in Monitoring-Skripte oder Benachrichtigungen einbinden kannst. So erfährst du von einem kranken Dienst, bevor deine Nutzer es tun.

Häufige Fragen

Beim Einrichten von Healthchecks tauchen typische Stolpersteine auf. Diese Antworten helfen dir schnell weiter.

Warum bleibt mein Container auf „starting“ stehen?

Solange die start_period läuft oder noch keine erfolgreiche Prüfung stattgefunden hat, zeigt Docker den Status starting. Prüfe mit docker inspect --format '{{json .State.Health}}' container die letzten Ausgaben deines Test-Befehls – meist stimmt der Pfad oder der Port nicht.

Braucht der Healthcheck curl im Image?

Der Test-Befehl läuft im Container, also muss das Werkzeug dort vorhanden sein. Bei schlanken Images fehlt curl oft. Nutze dann wget, das eingebaute Kommando deiner Anwendung oder installiere curl gezielt im Dockerfile.

Kann ich einen im Image definierten Healthcheck abschalten?

Ja. In Compose setzt du healthcheck: { disable: true }, beim docker run nutzt du --no-healthcheck. Das ist praktisch, wenn du in einer bestimmten Umgebung eine andere Prüfung verwenden möchtest.

Fazit

Ein Healthcheck macht aus „der Container läuft“ ein belastbares „der Dienst funktioniert“. Definiere Prüfbefehl, Intervall und Fehlversuche – in Compose oder im Dockerfile – und du erkennst Probleme, bevor deine Nutzer es tun. Mit depends_on und service_healthy steuerst du zusätzlich die Startreihenfolge. In Kombination mit einer Restart-Policy hältst du deine Dienste zuverlässig am Laufen.