Docker Container selbstheilend machen: HEALTHCHECK, Restart-Policies & Watchtower

Deine Docker-Container laufen zuverlässig – bis sie es nicht mehr tun. Ein Prozess stirbt, ein Dienst hängt, keiner merkt’s. Genau das passiert in Homelabs ständig: Der Dienst läuft „irgendwie“, aber wenn man nachschaut, ist die Web-UI schon seit Stunden nicht erreichbar.

Docker bietet drei mächtige Mechanismen, um Container selbstheilend zu machen. Richtig kombiniert laufen deine Dienste monatelang ohne manuelles Eingreifen – selbst wenn ein Prozess crasht.

1. Restart-Policies: Das Fundament

Die einfachste Schutzschicht ist die restart-Policy im Docker-Compose-File oder beim docker run. Docker unterstützt vier Modi:

Policy	Verhalten
`no`	Container wird nie automatisch neu gestartet (Default)
`always`	Immer neu starten, auch nach docker stop oder Docker-Daemon-Neustart
`unless-stopped`	Neu starten, außer der Container wurde explizit gestoppt
`on-failure`	Nur bei Exit-Code ungleich 0 neu starten

Empfehlung für die meisten Dienste: unless-stopped. So starten Container nach einem Host-Neustart automatisch, aber du kannst sie trotzdem manuell stoppen.

2. HEALTHCHECK: Wissen, dass es läuft

Eine Restart-Policy allein reicht nicht. Wenn der Prozess läuft, aber die Anwendung hängt, meldet Docker „running“, obwohl der Container faktisch tot ist.

Hier kommt HEALTHCHECK ins Spiel. Docker führt regelmäßig einen Befehl im Container aus und markiert den Status als healthy, unhealthy oder starting. In Docker Compose sieht das so aus:

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

Die Optionen im Detail:

test – Der Befehl, der die Gesundheit prüft. Exit-Code 0 = healthy, 1 = unhealthy
interval – Wie oft wird geprft? (Default: 30s)
timeout – Nach welcher Zeit gilt ein Check als fehlgeschlagen? (Default: 30s)
retries – Wieviele Fehlschlge bis unhealthy gesetzt wird? (Default: 3)
start_period – Anlaufphase, in der Fehlschlge nicht zhlen

3. HEALTHCHECK + Restart kombinieren mit autoheal

Docker startet einen Container mit unhealthy-Status leider nicht automatisch neu. Hier hilft autoheal (willfarrell/autoheal), ein Mini-Container, der periodisch prft und unhealthy-Container neu startet:

services:
  autoheal:
    image: willfarrell/autoheal
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - AUTOHEAL_CONTAINER_LABEL=autoheal=true
      - AUTOHEAL_INTERVAL=60

Markiere deine zu berwachenden Container mit labels: autoheal=true, und autoheal restartet sie bei unhealthy.

4. Watchtower: Automatische Updates

Container aktuell zu halten ist fast genauso wichtig wie sie laufen zu lassen. Watchtower aktualisiert laufende Container automatisch, sobald ein neues Image verfgbar ist:

services:
  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *

Der Cron-Ausdruck bedeutet: tglich um 4 Uhr morgens prfen und updaten. Mit CLEANUP=true werden alte Images gelscht.

5. Komplettes Beispiel: Self-Healing Stack

So sieht ein vollstndiges docker-compose.yml mit allen drei Mechanismen aus:

services:
  nginx:
    image: nginx:alpine
    restart: unless-stopped
    labels:
      - autoheal=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
    ports:
      - "80:80"

  autoheal:
    image: willfarrell/autoheal
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *

Schutzschichten-Modell:

Schicht 1: restart: unless-stopped fr alle Container
Schicht 2: healthcheck + autoheal erkennt hngende Container
Schicht 3: Watchtower hlt Container aktuell
Schicht 4: Uptime Kuma / Prometheus als externe berwachung

Fazit

Ein selbstheilendes Homelab braucht nur ein paar Zeilen Docker-Konfiguration plus einen Mini-Container fr autoheal. Die Investition ist minimal, der Gewinn an Zuverlssigkeit enorm. Deine Container laufen, wenn du sie brauchst – ohne dass du jede Nacht nachschauen musst, ob noch alles steht.

Welche Mechanismen setzt du ein? Nutzt du autoheal oder arbeitest du mit Uptime Kuma-Restart-Webhooks?