Docker Healthcheck konfigurieren – Container-Gesundheit überwachen 2025

Was ist ein Docker Healthcheck?

Ohne Healthcheck weiß Docker nur ob ein Container-Prozess läuft – nicht ob die Anwendung antwortet. Ein Healthcheck prüft aktiv ob der Service funktioniert.

Zustände:

• healthy – Healthcheck erfolgreich
• unhealthy – Healthcheck schlägt fehl (Container kann neugestartet werden)
• starting – Wartezeit nach Container-Start
• none – kein Healthcheck konfiguriert

Healthcheck im Dockerfile

FROM nginx:alpine

# HTTP Healthcheck
HEALTHCHECK --interval=30s \
            --timeout=5s \
            --start-period=10s \
            --retries=3 \
  CMD wget -q --spider http://localhost:80/ || exit 1

Parameter:

Healthcheck im Docker Compose

services:
  api:
    image: myapi:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

depends_on mit Healthcheck

services:
  api:
    image: myapi:latest
    depends_on:
      db:
        condition: service_healthy  # Wartet bis DB healthy ist!
      redis:
        condition: service_healthy

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10

Ohne diese Konfiguration startet api bevor die Datenbank bereit ist – häufige Ursache für Startup-Fehler!

Healthcheck-Status prüfen

# Status anzeigen
docker inspect --format='{{.State.Health.Status}}' mein-container

# Letzte Checks anzeigen
docker inspect --format='{{json .State.Health}}' mein-container | jq

# Alle ungesunden Container finden
docker ps --filter "health=unhealthy"

Restart-Policy

services:
  api:
    restart: unless-stopped
    # Optionen: no, always, on-failure, unless-stopped

on-failure:5 – Maximal 5 Neustarts bei Fehler, dann aufgeben.

FAQ

Startet Docker Container automatisch neu wenn unhealthy?
Nicht automatisch mit Docker Compose – das ist Sache der Restart-Policy (restart: always). In Docker Swarm werden unhealthy Container von selbst neu deployed.

Welche CMD-Variante soll ich nutzen?
CMD ["curl", "-f", "http://..."] – keine Shell nötig, direkter. CMD-SHELL wenn Sie Shell-Features (Pipes, &&) brauchen.

Fazit

Healthchecks sind essenziell für produktive Container-Umgebungen. Besonders depends_on: condition: service_healthy verhindert eine Klasse von Startup-Race-Conditions komplett.

Container-Infrastruktur für KMU in Heidelberg, Mannheim und Rhein-Neckar. Anfragen.