Healthchecks für Docker-Container

Was dieser Artikel über Docker-Healthchecks behandelt

• Was ein Healthcheck ist.
• Wie man Healthchecks in Dockerfiles und Compose definiert.
• Wie Docker bei Fehlern reagiert.
• Praktische Beispiele für Webdienste, Datenbanken und Ollama.
• Tipps und typische Fehler.

Einleitung: Healthchecks für Docker-Container

Ein Docker-Container kann laufen, ohne dass die darin enthaltene Anwendung tatsächlich bereit oder funktionsfähig ist. Healthchecks helfen, den Zustand einer Anwendung regelmässig zu prüfen. Docker markiert einen Container dann als healthy oder unhealthy und kann bei Bedarf automatisch neu starten oder Alarme auslösen.

Dieser Artikel zeigt, wie Healthchecks funktionieren und wie man sie für typische KI-Dienste wie Ollama, Open WebUI oder Datenbanken einrichtet.

Wichtige Begriffe

• Healthcheck: Regelmässige Prüfung der Anwendungsgesundheit.
• Interval: Zeit zwischen zwei Prüfungen.
• Timeout: Maximale Wartezeit auf das Prüfergebnis.
• Start Period: Zeit, in der Fehler ignoriert werden, um das Hochfahren zu ermöglichen.
• Retries: Anzahl der erlaubten Fehlversuche, bevor ein Container unhealthy wird.
• Restart Policy: Verhalten bei einem Neustart.
• Exit Code: Rückgabewert des Healthcheck-Befehls. 0 bedeutet gesund, 1 bedeutet ungesund.

Warum Healthchecks wichtig sind

• Container werden erst als bereit markiert, wenn die Anwendung läuft.
• Fehler werden früh erkannt.
• Reverse Proxies und Load Balancer können gesunde Container bevorzugen.
• Automatische Neustarts erhöhen Verfügbarkeit.
• Monitoring kann auf den Health-Status reagieren.

Healthcheck im Dockerfile

FROM nginx:latest

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

Dieser Healthcheck prüft alle 30 Sekunden, ob der lokale Webserver antwortet.

Healthcheck in Docker Compose

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

Status abfragen

docker ps

Die Spalte STATUS zeigt (healthy) oder (unhealthy) an.

Detail:

docker inspect --format='{{.State.Health.Status}}' containername

Beispiel: Ollama

services:
  ollama:
    image: ollama/ollama
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11434/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped

Dieser Healthcheck prüft, ob die Ollama-API erreichbar ist.

Beispiel: Open WebUI

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    restart: unless-stopped

Beispiel: PostgreSQL

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    restart: unless-stopped

Komplexere Prüfungen

Manchmal reicht ein simpler HTTP-Status nicht. Man kann eigene Skripte nutzen, die prüfen, ob kritische Funktionen funktionieren:

#!/bin/sh
if curl -f http://localhost/api/health | grep -q '"ok":true'; then
  exit 0
else
  exit 1
fi

Im Container ablegen und als Healthcheck aufrufen.

Restart-Politiken

Politik	Verhalten
no	Nie neu starten.
on-failure	Nur bei Fehlercode.
always	Immer neu starten.
unless-stopped	Neu starten, ausser manuell gestoppt.

Empfohlene Kombination:

restart: unless-stopped

Healthcheck deaktivieren

Wenn ein vorgefertigtes Image einen unpassenden Healthcheck hat, kann man ihn überschreiben:

services:
  app:
    image: irgendein-image
    healthcheck:
      disable: true

Tipps

• Healthcheck sollte einen sinnvollen Endpunkt prüfen, nicht nur den Prozess.
• Start Period grosszügig wählen.
• Intervall nicht zu kurz setzen, um Ressourcen zu schonen.
• Timeout an tatsächliche Antwortzeit anpassen.
• Logs der Healthchecks beobachten.
• Eigene Healthcheck-Skripte kurz halten.

Typische Stolpersteine

• Zu strenges Intervall: Hohe Last durch ständige Prüfungen.
• Zu kurze Start Period: Container wird während des Starts als ungesund markiert.
• Falsches Protokoll: HTTPS prüfen, obwohl HTTP läuft.
• Fehlende Tools im Image: curl nicht vorhanden, Skript bricht ab.
• Nur Prozess prüfen: Anwendung ist hängend, aber Prozess läuft.
• Keine Restart-Policy: Ungesunde Container laufen weiter.
• Healthcheck-Ausgaben in Logs: Verwirrende Log-Einträge.

Weiterführende Links und Infos

• BotServ.de Docker Monitoring
• BotServ.de Docker Logs
• BotServ.de Docker Sicherheit
• BotServ.de Docker Compose

FAQ: Docker-Healthchecks

Braucht jeder Container einen Healthcheck? Nein, aber für wichtige Dienste ist er empfohlen.

Wie oft wird ein Healthcheck ausgeführt? Standardmässig alle 30 Sekunden, aber einstellbar.

Was passiert bei unhealthy? Docker zeigt den Status an. Mit Restart-Policy kann der Container neu gestartet werden.

Kann ich eigene Befehle nutzen? Ja, beliebige Shell- oder CMD-Prüfungen sind möglich.

Sind Healthchecks dasselbe wie Readiness-Probes in Kubernetes? Ähnlich, aber Kubernetes bietet zusätzlich Readiness und Startup Probes.

Quellen und weiterführende Literatur

• Docker Healthcheck: https://docs.docker.com/engine/reference/builder/#healthcheck
• Docker Restart Policy: https://docs.docker.com/config/containers/start-containers-automatically/
• Compose Healthcheck: https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck

Zusammenfassung: Healthchecks für Docker-Container

Healthchecks sind eine einfache Möglichkeit, die tatsächliche Verfügbarkeit von Docker-Containern zu überwachen. Sie lassen sich im Dockerfile oder in Docker Compose definieren und arbeiten eng mit Restart-Policies zusammen. Für wichtige KI-Dienste wie Ollama, Open WebUI oder Datenbanken sollten gezielte Endpunktprüfungen eingerichtet werden. Wichtig sind sinnvolle Intervalle, ausreichende Startzeiten und präzise Prüfmethoden. Wer Healthchecks früh einbaut, verbessert die Stabilität des gesamten Stacks spürbar.