Home Assistant im Docker-Container sicher updaten: mein Workflow mit Backup, Test und Rollback

Mein Home Assistant läuft seit Jahren als nackter Docker-Container — kein Supervisor, kein HAOS, nur das offizielle Image und ein Mount auf mein Config-Verzeichnis. Das ist schlank und kontrollierbar, hat aber einen Preis: Es gibt keinen „Update“-Knopf im UI und keinen automatischen Snapshot. Ein Major-Update kann meine KNX-Heizung, die PV-Sensoren und ein halbes Dutzend HACS-Integrationen gleichzeitig brechen, und wenn ich Pech habe, merke ich es erst, wenn abends das Bad kalt bleibt.

Nach ein paar schmerzhaften Updates habe ich mir eine feste Prozedur angewöhnt, die ich jedes Mal stur abarbeite. Der Kern: Die Reihenfolge ist alles, der Container wird neu erstellt statt in-place überschrieben, und ich notiere mir vorher den exakten Rückweg. Hier ist der komplette Ablauf.

Warum die Reihenfolge fast alle scheitern lässt

Der häufigste Fehler ist, zuerst den Home-Assistant-Core zu ziehen und sich dann zu wundern, dass HACS-Integrationen kaputt sind. Tatsächlich ist es genau andersherum sicherer: Erst die Custom Components und HACS aktualisieren und gegen die noch laufende ALTE Core-Version testen, dann erst den Core anheben. So trennst du die zwei Fehlerquellen sauber voneinander. Klemmt nach dem HACS-Update etwas, weißt du, dass es an der Integration liegt — und nicht an einem Core-Bruch, den du gleichzeitig eingefahren hast.

Konkret heißt das: Ich öffne HACS, aktualisiere die ausstehenden Custom Components einzeln (bei mir typischerweise Dinge wie der Shelly- oder Huawei-Solar-Integration), starte Home Assistant einmal neu — noch auf der alten Core-Version — und prüfe, ob alles funktioniert. Erst wenn dieser Zwischenstand sauber ist, gehe ich an das Image.

Schritt 1 — Voll-Backup, bevor irgendetwas angefasst wird

Vor jedem Update sichere ich das komplette Config-Verzeichnis. Bei einer Docker-Installation ist das schlicht der Ordner, den du in den Container mountest — er enthält die configuration.yaml, die Datenbank, die .storage-Registries und alle YAML-Pakete. Wenn dieser Ordner gesichert ist, ist dein gesamter Zustand gesichert. Lege die Kopie außerhalb des Container-Mounts ab (anderes Verzeichnis oder ein anderer Host), nicht daneben.

Wichtig: Stoppe den Container vor dem Backup oder nimm zumindest die laufende SQLite-Datenbank in Kauf. Bei einem Major-Update mit Datenbank-Migration ist ein sauberer Snapshot des alten Stands der einzige Weg, den die Migration nicht ohnehin mitnimmt.

Schritt 2 — die alte Image-ID notieren (dein echter Rollback)

Das ist der Schritt, den fast alle Anleitungen weglassen, und er ist der wichtigste. „Rollback“ heißt bei Docker nicht „nochmal stable ziehen“ — das holt ja wieder die neue Version. Ein echter Rückweg geht nur über die exakte Image-ID, mit der dein Container vor dem Update lief. Die notierst du dir, bevor du irgendetwas ziehst:

sudo docker inspect homeassistant --format '{{.Image}}'
# Rollback: docker run ... <ALTE_IMAGE_ID>

Schreib dir diese ID weg (Textdatei, Notiz, egal). Solange das alte Image lokal nicht weggeräumt wurde, kannst du jederzeit einen neuen Container mit <ALTE_IMAGE_ID> statt dem stable-Tag starten und bist in Sekunden wieder auf dem alten Stand — mit deinem (gesicherten) alten Config-Ordner.

Schritt 3 — den Container neu erstellen statt in-place

Jetzt das eigentliche Core-Update. Ich aktualisiere nie in-place, sondern stoppe den Container, ziehe das neue Image und erstelle den Container komplett neu — mit exakt demselben Mount und denselben Flags wie vorher. So bleibt der Container-Zustand vorhersehbar und es schleppt sich keine alte Laufzeit-Konfiguration mit:

sudo docker stop homeassistant
sudo docker pull ghcr.io/home-assistant/home-assistant:stable
sudo docker rm homeassistant && sudo docker run -d \
  --name homeassistant --restart unless-stopped --network host \
  -v /home/USER/homeassistant:/config \
  ghcr.io/home-assistant/home-assistant:stable

Ersetze /home/USER/homeassistant durch deinen tatsächlichen Config-Pfad. Der --network host-Modus ist für viele lokale Integrationen (Discovery, Modbus, KNX) praktisch Pflicht; behalte exakt die Flags bei, die dein alter Container hatte — ein vergessenes Flag ist eine eigene Klasse von „nach dem Update geht X nicht mehr“-Fehlern.

Schritt 4 — auf die Datenbank-Migration warten

Bei einem Major-Update wandert Home Assistant beim ersten Start sein Datenbank-Schema. Das kann je nach Größe der Datenbank etliche Minuten dauern, und in dieser Zeit antwortet die API noch nicht. Nicht ungeduldig werden und den Container neu starten — das bricht die Migration mittendrin ab. Ich beobachte stattdessen, ab wann die API wieder antwortet:

watch -n 5 'curl -s -m 3 http://HA_HOST:8123/api/ 2>/dev/null'

Ersetze HA_HOST durch die Adresse deiner Instanz. Sobald das Kommando eine JSON-Antwort liefert statt einer leeren Zeile, ist der Core hochgekommen und die Migration durch. Parallel lohnt ein Blick in das Container-Log (docker logs -f homeassistant), das die Migration mitprotokolliert.

Schritt 5 — die Post-Update-Checkliste

Ein grüner API-Endpunkt heißt noch nicht, dass das Smart Home funktioniert. Ich habe eine kurze Checkliste der Dinge, die bei mir nach Updates erfahrungsgemäß zuerst zicken — vor allem alles, was über lokale Bus-Systeme läuft. Ich gehe sie nach jedem Update aktiv durch:

- [ ] KNX Thermostaten reagieren (Preset-Mode wechseln)
- [ ] Fenstersensoren korrekt (alle off nach Startup)
- [ ] Solar/PV Daten kommen rein
- [ ] HACS funktioniert
- [ ] Automationen aktiv (Rollo-Zeitsteuerung, Heizung Tag/Nacht)

Gerade die PV- und Modbus-Sensoren prüfe ich genau, weil die nach einem Core-Sprung gerne mal anders gemappt werden — wie ich die überhaupt anbinde, steht im Modbus-Grundlagen-Post. Stimmt etwas nicht, greife ich auf den Rollback aus Schritt 2 zurück, statt im laufenden Betrieb herumzudoktern.

Wenn das Update schiefgeht: der Rollback in der Praxis

Der Rückweg ist genau die Umkehrung von Schritt 3, nur mit der alten Image-ID. Container stoppen und entfernen, den alten Config-Ordner aus dem Backup zurückspielen (wichtig, falls die Migration das Schema schon angefasst hat — eine migrierte Datenbank läuft auf dem alten Core nicht zuverlässig), und einen neuen Container mit <ALTE_IMAGE_ID> starten. Genau deshalb sind Backup und notierte Image-ID kein optionales Extra, sondern die zwei Dinge, die einen schlechten Update-Abend von einem komplett kaputten Wochenende trennen.

Mein autarker Energiehaushalt zum Beispiel hängt an einer Kette aus Modbus-Sensoren und Template-Berechnungen — wenn der Autarkiegrad nach dem Update plötzlich unavailable ist, weiß ich, dass eine Datenquelle weggebrochen ist, und entscheide anhand der Checkliste, ob ich nachbessere oder zurückrolle. Wie diese abgeleiteten Kennzahlen aufgebaut sind, beschreibe ich in den Autarkie-Sensoren.

Häufige Fragen

Warum nicht einfach Watchtower für automatische Updates?

Watchtower zieht stillschweigend das neueste Image und erstellt den Container neu — das ist genau das Szenario, das ich vermeiden will. Ein Major-Update mit Datenbank-Migration und potenziell brechenden HACS-Integrationen will ich kontrolliert, mit Backup und notierter Rollback-ID fahren, nicht nachts um drei automatisch. Für reine Minor-/Patch-Releases ist Watchtower verlockend, aber Home Assistant unterscheidet im stable-Tag nicht zwischen Patch und Major — deshalb mache ich es bewusst von Hand.

Reicht das Home-Assistant-Backup nicht statt eines Ordner-Backups?

Das eingebaute Backup gibt es in der reinen Docker-Variante (ohne Supervisor) nicht als Knopf — es ist eine Supervisor-Funktion. In einem nackten Container ist dein Config-Mount der Backup. Genau das macht ihn so einfach: Ein Verzeichnis kopieren sichert deinen kompletten Zustand inklusive Datenbank und .storage-Registries.

Wie lange behalte ich das alte Image?

Solange das neue Update sich in mehreren Tagen Normalbetrieb bewährt hat. Erst dann räume ich mit docker image prune auf. Vorher ist das alte Image dein einziger Sekunden-Rollback — ein paar hundert Megabyte Plattenplatz sind das allemal wert. Ich notiere mir Image-ID und Datum, damit ich weiß, welches Image zu welcher funktionierenden Config gehört.

Was, wenn die API nach dem Update gar nicht hochkommt?

Dann zuerst ins Container-Log schauen (docker logs homeassistant). Häufigste Ursachen nach einem Major-Sprung sind eine entfernte/umbenannte YAML-Option oder eine HACS-Integration, die mit dem neuen Core inkompatibel ist. Steht im Log ein konkreter Fehler, kannst du gezielt nachbessern; ist es undurchsichtig oder zieht sich die Downtime, ist der saubere Schritt der Rollback aus Schritt 2 statt minutenlanges Raten am laufenden System.