Docker Compose Restart-Policies erklärt

Der Strom fiel kurz aus, der Host startete neu, und die Hälfte des Homelab-Stacks kam von selbst wieder hoch — die andere Hälfte blieb einfach stehen, beendet, und wartete auf ein docker compose up, das nie kam. Jeder Container in diesem Stack hatte eine restart:-Zeile. Es war nur nicht überall dieselbe Zeile, und genau das ist das Problem, das dieser Artikel löst.

Die vier Restart-Policies in einer Tabelle

Policy	Neustart bei Absturz	Neustart nach Host-/Daemon-Neustart	Neustart nach manuellem docker compose stop	Typischer Einsatz
no (Standard)	Nein	Nein	— (bereits gestoppt)	Alles, was Sie manuell starten und stoppen möchten
always	Ja	Ja	Ja, sobald der Daemon neu startet	Dienste, die niemals ausfallen dürfen
unless-stopped	Ja	Ja	Nein — bleibt gestoppt	Die meisten dauerhaft laufenden selbst gehosteten Dienste
on-failure[:N]	Nur bei Exit-Code ungleich null	Nein (außer mitten im Retry)	—	Einmalige Jobs, Migrationen, Backup-Läufe

Dockers eigene Dokumentation zu Restart-Policies deckt die Mechanik ab; was sie nicht verrät, ist, welche Policy vor Jellyfin gehört und welche vor einen Wegwerf-Backup-Container. Genau diese Entscheidung ist der eigentliche Sinn dieses Artikels.

no — der Standard, den niemand bemerkt, bis der Neustart kommt

Lassen Sie restart: ganz weg oder schreiben Sie restart: "no", tut Compose beim Beenden des Containers oder beim Host-Neustart schlicht nichts. Das ist in Ordnung für einen Container, den Sie bewusst starten und im Blick behalten. Es ist nicht in Ordnung für einen Dienst, den Sie für "läuft einfach" halten — wie im Einsteiger-Guide zum Homelab-Aufbau beschrieben, ist die häufigste Überraschung bei Einsteigern ein Dienst, der wochenlang nur deshalb lief, weil der Host nie neu gestartet wurde, und nach dem ersten Kernel-Update spurlos verschwand.

always — startet sogar nach einem manuellen Stopp neu

restart: always startet den Container bei Absturz, bei Host-Neustart und — der Teil, den die meisten übersehen — bei einem Neustart des Docker-Daemons neu, selbst wenn Sie zuvor manuell docker stop ausgeführt hatten. Docker merkt sich nicht, dass Sie ihn absichtlich gestoppt haben, sondern nur die Policy. Auf diesem Homelab läuft Jellyfin mit genau dieser Policy, weil ein toter Medienserver nach einem Stromausfall genau die Art Ausfall ist, die im Haushalt innerhalb von Minuten auffällt:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    restart: always
    ports:
      - "8096:8096"
    volumes:
      - jellyfin_config:/config
      - jellyfin_media:/media

unless-stopped — die sicherere Standardwahl für fast alles

unless-stopped verhält sich bei Abstürzen und Neustarts identisch zu always, mit einem Unterschied, der im Alltag zählt: Wenn Sie den Container manuell stoppen, bleibt er auch nach einem Neustart des Docker-Daemons gestoppt. Genau dieser eine Unterschied macht unless-stopped, nicht always, zur sinnvollen Standardwahl für die meisten selbst gehosteten Dienste — Sie bekommen Ausfallsicherheit, ohne die Möglichkeit zu verlieren, etwas bewusst für Wartungsarbeiten offline zu nehmen. Sowohl Vaultwarden als auch n8n laufen im selben Stack mit dieser Policy:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    restart: unless-stopped
    volumes:
      - vw_data:/data

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n

Vollständige Einrichtung und Hardware-Hinweise zu beiden Diensten finden Sie im Vaultwarden-Selbsthosting-Guide und im n8n-Free-Tier-Überblick.

on-failure[:N] — für Jobs, nicht für Dienste

on-failure löst einen Neustart nur aus, wenn der Container mit einem Exit-Code ungleich null beendet wird — ein sauberes exit 0 gilt als Erfolg, und Compose lässt ihn gestoppt. Das ist die richtige Policy für alles, was einmal laufen und dann fertig sein soll, nicht auf einem Port lauschen soll. Fügen Sie mit on-failure:3 eine Retry-Obergrenze hinzu, damit ein wirklich kaputter Job nicht endlos schleift:

services:
  restic-backup:
    image: restic/restic:latest
    restart: on-failure:3
    command: backup /data --repo /backup-repo
    volumes:
      - app_data:/data:ro
      - backup_repo:/backup-repo

Entscheidungshilfe: welche Policy für welchen Dienst

Diensttyp	Empfohlene Policy	Warum
Medienserver (Jellyfin, Plex)	always	Ausfall fällt allen im Haushalt sofort auf
Zugangsdaten-/Passwort-Manager (Vaultwarden)	unless-stopped	Muss Neustarts überstehen, wird aber manchmal bewusst für Backups gestoppt
Automatisierungs-Engine (n8n)	unless-stopped	Gleiche Logik — ausfallsicher per Standard, bewusst stoppbar
Reverse Proxy	unless-stopped	Steht vor allem anderen; soll von selbst zurückkommen, aber einen bewussten Wartungsstopp nicht unterlaufen
Datenbank (Postgres, MariaDB)	unless-stopped	Muss Neustarts überstehen; always vermeiden, damit ein bewusster Stopp vor einer Festplattenoperation wirklich greift
Einmaliger Job (Backup, Migration, Cron-artige Aufgabe)	on-failure:3	Soll durchlaufen und gestoppt bleiben, nur bei echtem Fehler erneut versuchen

Der Neustart-Test: so prüfen Sie wirklich, ob Ihre Policies funktionieren

Eine Compose-Datei zu lesen beweist nicht, dass die Policy funktioniert — ein Neustart schon. Führen Sie nach dem Anpassen der restart:-Werte sudo reboot aus, warten Sie, bis der Host wieder hochfährt, und prüfen Sie dann:

docker compose ps

Jeder Dienst, den Sie auf always oder unless-stopped gesetzt haben, sollte Up anzeigen. Zeigt etwas Exited an, hat es entweder keine Restart-Policy, wurde vor dem Neustart absichtlich gestoppt — oder, der Fall, der die meisten überrascht: Docker selbst ist auf Systemd-Ebene nicht für den Boot-Start aktiviert, sodass gar keine Container-Restart-Policy greift, wie im Vergleich Docker vs. virtuelle Maschinen erklärt. Prüfen Sie mit systemctl is-enabled docker, ob der Daemon beim Booten startet, bevor Sie sich auf irgendeine Restart-Policy verlassen.

Fazit

Wählen Sie unless-stopped als Haus-Standard für alles Dauerhafte, reservieren Sie always für die wenigen Dienste, bei denen "startet auch nach manuellem Stopp neu" wirklich gewünscht ist, und behalten Sie on-failure strikt für Jobs, die tatsächlich fertig werden. Beweisen Sie es dann mit einem echten Neustart, nicht nur mit einem Blick in die Compose-Datei.

Häufig gestellte Fragen

Was ist die Standard-Restart-Policy in Docker, wenn Sie keine setzen?

no. Der Container startet nicht automatisch neu — weder bei einem Absturz noch bei einem Daemon- oder Host-Neustart. Sie müssen ihn jedes Mal manuell starten.

Startet docker compose restart: always nach einem Host-Neustart neu?

Ja. always startet den Container bei Absturz, bei Docker-Daemon-Neustart und bei Host-Neustart neu — auch dann, wenn Sie ihn vor dem Neustart manuell gestoppt hatten.

Was ist der Unterschied zwischen always und unless-stopped in Docker?

Beide überstehen Abstürze und Neustarts. Der Unterschied liegt bei einem manuellen Stopp: always startet den Container nach einem Daemon-Neustart auch dann wieder, wenn Sie ihn selbst gestoppt hatten; unless-stopped respektiert diesen manuellen Stopp und bleibt gestoppt.

Wie begrenzen Sie die Neustart-Versuche bei on-failure?

Fügen Sie nach einem Doppelpunkt eine Zahl hinzu, z. B. restart: on-failure:3. Docker bricht nach drei fehlgeschlagenen Versuchen ab, statt unbegrenzt weiter zu versuchen.