Home Assistant mit Docker: die lokale Smart-Home-Zentrale

Home Assistant Container ist die Docker-Variante der Open-Source-Smart-Home-Zentrale Home Assistant. Anders als bei Home Assistant OS (HAOS) gibt es keinen Supervisor und keine Ein-Klick-Add-ons (heute „Apps“ genannt), dafür einen schlanken Container, den Sie per docker compose betreiben. Die Variante passt, wenn bereits ein Linux-Server mit Docker läuft und Sie Ihr Smart Home lokal, ohne Cloud steuern wollen. Sie richten compose.yaml, Onboarding, erste Integrationen, eine Automatisierung sowie Update- und Backup-Workflow ein.

Voraussetzungen

Home Assistant Container ist genügsam und braucht keine GPU.

1. Linux-Server mit Docker Engine ab Version 23 und Plugin Docker Compose, etwa Debian 12 oder Ubuntu 24.04. Docker Desktop wird laut Home-Assistant-Doku nicht unterstützt. Ein Raspberry Pi 4/5, Mini-PC oder vorhandener Heimserver reicht.
2. Architektur: 64 Bit (amd64 oder aarch64). Für 32-Bit-Systeme (i386, armhf, armv7) gibt es seit Version 2025.12 keine neuen Images mehr.
3. CPU, RAM, Speicher: Die Doku nennt für die Container-Variante keine Mindestwerte. Richtwert ist der HAOS-Wert von 2 Kernen, mindestens 2 GB RAM und 32 GB Speicher; das Image belegt rund 2 GB.
4. GPU: Für Home Assistant nicht erforderlich. Erst rechenintensive Zusatzdienste in eigenen Containern (z. B. lokales LLM-Serving oder Bildverarbeitung) brauchen eine GPU plus nvidia-container-toolkit.
5. Netzwerk: Feste IP oder DHCP-Reservierung, damit die Web-UI unter derselben Adresse erreichbar bleibt.
6. Optional: ein USB-Stick für Zigbee oder Z-Wave sowie eine Domain plus Reverse-Proxy, falls Sie von außen zugreifen wollen.

Docker und Compose sind installiert, wenn folgende Befehle Versionen ausgeben:

docker --version
docker compose version

Schritt 1: Projektverzeichnis anlegen

Legen Sie ein eigenes Verzeichnis für den Stack an. Darin liegen die compose.yaml und das persistente config-Verzeichnis.

mkdir -p ~/homeassistant/config
cd ~/homeassistant

In config landen Konfiguration, Datenbank, Automatisierungen und Geheimnisse. Wer dieses Verzeichnis sichert, sichert die komplette Instanz.

Verifizieren: pwd zeigt …/homeassistant, ls listet den leeren Ordner config.

Schritt 2: compose.yaml erstellen

Erstellen Sie in ~/homeassistant die Datei compose.yaml. Das Beispiel entspricht dem offiziellen Setup: Image stable, persistentes ./config-Volume, network_mode: host für die Auto-Discovery, Zeitzone, robuster Neustart-Modus und 60 Sekunden zum sauberen Herunterfahren.

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    stop_grace_period: 60s
    privileged: true
    network_mode: host
    environment:
      TZ: Europe/Berlin

Was die wichtigsten Zeilen bedeuten:

1. image: Der Tag stable liefert die aktuelle stabile Version. Alternativ beta, dev oder eine feste Version wie 2026.10.0 (Pinning); feste Tags machen Updates planbarer.
2. volumes: ./config:/config hält alle Daten außerhalb des Containers persistent. /etc/localtime übernimmt die Host-Zeit, /run/dbus wird für Bluetooth und dbus benötigt.
3. network_mode: host: Pflicht für die automatische Geräteerkennung über mDNS, SSDP und UPnP. Die Web-UI läuft dann direkt auf Port 8123 des Hosts.
4. privileged: true: Aus dem offiziellen Compose-Beispiel, gibt Hardware- und USB-Zugriff. Alternativ reichen Sie gezielt einzelne devices bzw. cap_add durch (Schritt 6).
5. TZ: Setzen Sie die Zeitzone, sonst stimmen Zeitstempel und zeit- bzw. sonnenbasierte Automationen nicht.

Verifizieren: docker compose config gibt die Konfiguration ohne Fehlermeldung aus.

Schritt 3: Container starten

Starten Sie den Stack im Hintergrund:

docker compose up -d

Beim ersten Start zieht Docker das Image und Home Assistant initialisiert config; das dauert ein bis zwei Minuten. Fortschritt:

docker logs -f homeassistant

Die Container-Logs zeigen vor allem Startmeldungen des Init-Systems (s6-rc), Details stehen in config/home-assistant.log. Strg+C beendet die Live-Logs, ohne den Container zu stoppen.

Verifizieren: docker compose ps zeigt den Container als Up. curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8123/ liefert 302 (Weiterleitung zum Onboarding). Im Test lief Version 2026.10.0 nach gut einer Minute.

Schritt 4: Web-UI und Ersteinrichtung (Onboarding)

Öffnen Sie http://SERVER-IP:8123 (IP Ihres Servers). Es gibt keine Standard-Zugangsdaten; das Onboarding führt durch die Ersteinrichtung:

1. Legen Sie Ihr Admin-Konto an (Name, Benutzername, sicheres Passwort) und bewahren Sie die Daten sicher auf.
2. Vergeben Sie einen Namen für Ihr Zuhause und setzen Sie den Standort; er bestimmt Sonnenauf- und -untergang für Automationen.
3. Stellen Sie Einheiten und Zeitzone ein (passend zur TZ aus der compose.yaml).
4. Am Ende zeigt Home Assistant automatisch erkannte Geräte, dank network_mode: host oft schon Fernseher, Drucker, Mediaplayer oder smarte Steckdosen.

Admin-Konto anlegen: 1 Name, 2 Benutzername, 3 Passwort zweimal eingeben, 4 auf Benutzerkonto anlegen klicken.

Standort setzen: 1 Adresse suchen, 2 passenden Treffer auswählen, 3 auf Weiter klicken.

Danach landen Sie im Dashboard, der zentralen Oberfläche von Home Assistant.

Verifizieren: Nach der Anmeldung mit dem neuen Konto erscheint das Dashboard.

Schritt 5: Integrationen, Geräte und erste Automatisierung

Eine Integration verbindet Home Assistant mit einem Gerät oder Dienst. Jedes Gerät stellt Entitäten bereit (z. B. Schalter, Sensor, Licht), die Bausteine zum Steuern und Automatisieren.

Integration hinzufügen

Unter Einstellungen > Geräte & Dienste finden Sie bei Entdeckt die per Auto-Discovery gefundenen Geräte; Konfigurieren bindet sie ein. Fehlendes fügen Sie über Integration hinzufügen hinzu (Suche nach Hersteller oder Protokoll).

Integration hinzufügen: 1 Einstellungen öffnen, dort Geräte & Dienste, 2 Reiter Integrationen, 3 auf Integration hinzufügen klicken.

Erste Automatisierung anlegen

Eine Automatisierung besteht aus Auslöser (wann), Bedingung (nur wenn) und Aktion (was passiert). Beispiel: Beim Sonnenuntergang das Wohnzimmerlicht einschalten.

1. Gehen Sie zu Einstellungen > Automatisierungen & Szenen und klicken Sie auf Automatisierung erstellen > Neue Automatisierung.
2. Auslöser: Typ Sonne, Ereignis Sonnenuntergang.
3. Bedingung (optional): z. B. nur, wenn jemand zu Hause ist.
4. Aktion: Gerät bzw. Entität auswählen und Aktion Einschalten setzen.
5. Speichern und Namen vergeben - fertig.

Neue Automation: 1 Auslöser, 2 optional Bedingung, 3 Aktion hinzufügen. Speichern erscheint unten rechts, sobald etwas eingetragen ist.

Nach diesem Muster bauen Sie komplexere Abläufe ohne externe Cloud.

Verifizieren: Die neue Integration steht unter Geräte & Dienste ohne Fehlermeldung. In der Automatisierung über das Drei-Punkte-Menü Ausführen wählen: Das Licht schaltet ein, unter Traces erscheint der Lauf.

Schritt 6: USB-Sticks und Add-on-Ersatz (Zigbee, Z-Wave, MQTT)

Add-ons gibt es nur unter HAOS. In der Container-Variante betreiben Sie Dienste wie Mosquitto (MQTT), ESPHome, Zigbee2MQTT oder Z-Wave JS UI als eigene Docker-Container und verbinden sie über das Netzwerk mit Home Assistant.

USB-Stick durchreichen

Zigbee- oder Z-Wave-Sticks reichen Sie in den Container durch, und zwar über den stabilen by-id-Pfad statt /dev/ttyUSB0, der sich nach Reboot oder USB-Wechsel ändern kann.

# stabilen Pfad ermitteln
ls -l /dev/serial/by-id/
services:
  homeassistant:
    devices:
      - /dev/serial/by-id/usb-XXXXX:/dev/ttyUSB0

Tragen Sie den by-id-Pfad anstelle von usb-XXXXX ein. Ohne privileged: true kombinieren Sie diesen devices-Eintrag mit gezielten cap_add-Rechten.

Verifizieren: Nach docker compose up -d zeigt docker exec homeassistant ls -l /dev/ttyUSB0 das Gerät. Die Zigbee- oder Z-Wave-Integration findet den Stick ohne Fehlermeldung.

Schritt 7: Reverse-Proxy und HTTPS

Hinter einem Reverse-Proxy (z. B. Nginx oder Traefik) müssen Sie das freischalten, sonst beantwortet Home Assistant jede Anfrage über den Proxy mit 400: Bad Request. Seit Version 2026.8 legen Sie diese Einstellungen in der Oberfläche fest, nicht mehr in der configuration.yaml. Ein http:-Block wird nur beim ersten Start nach einem Update von einer älteren Version übernommen, bei einer Neuinstallation und jeder späteren Ergänzung ignoriert Home Assistant ihn. Öffnen Sie die Weboberfläche direkt unter http://SERVER-IP:8123, nicht über den Proxy:

1. Gehen Sie zu Einstellungen > System > Netzwerk, Abschnitt HTTP-Server, Bereich Reverse-Proxy.
2. Aktivieren Sie X-Forwarded-For vertrauen und tragen Sie unter Vertrauenswürdige Proxys die Adresse des Proxys ein: 127.0.0.1 und ::1, wenn der Proxy auf demselben Host läuft, bei einem Proxy-Container dessen Docker-Netz (z. B. 172.16.0.0/12), sonst die Netzadresse des Proxy-Netzes (z. B. 192.168.1.0/24), nicht die einzelne Host-IP.
3. Klicken Sie auf Speichern und Speichern und neu starten. Nach dem Neustart erscheint Neue HTTP-Serverkonfiguration bestätigen: Klicken Sie auf Bestätigen. Ohne Bestätigung stellt Home Assistant nach 5 Minuten die vorherige Konfiguration wieder her.

Entfernen Sie einen vorhandenen http:-Block aus der configuration.yaml; diese Zeile darf nichts ausgeben:

grep -n '^http:' config/configuration.yaml

Im Bridge-Modus statt Host-Netz (typisch hinter einem Proxy) geben Sie den Port frei und entfernen network_mode: host; die Auto-Discovery fällt dann weg:

services:
  homeassistant:
    ports:
      - "8123:8123"
    # network_mode: host dann entfernen (Auto-Discovery fällt weg)

Prüfen Sie Änderungen an der configuration.yaml vor dem Neustart. Ohne --config /config sucht das Skript an der falschen Stelle:

docker exec homeassistant python -m homeassistant --script check_config --config /config
docker compose restart homeassistant

Verifizieren: Über die Proxy-Adresse lädt die Anmeldeseite per HTTPS statt 400: Bad Request, unter Einstellungen > System > Reparaturen steht keine Meldung der HTTP-Integration, und config/home-assistant.log enthält nach dem Neustart keine Zeile your HTTP integration is not set-up for reverse proxies.

Schritt 8: Update- und Backup-Workflow

In der Container-Variante sind Updates manuell.

Update durchführen

Prüfen Sie vor jedem Update die Release Notes auf Breaking Changes und legen Sie ein Backup an. Dann:

docker compose pull homeassistant
docker compose up -d

docker compose up -d ersetzt den Container durch einen mit neuem Image; die Daten bleiben im ./config-Volume. stable kann größere Versionssprünge bringen, eine feste Version macht Updates kalkulierbarer.

Beim Update auf 2026.10 entfällt der veraltete Legacy-Modus des Home-Assistant-Anmeldeanbieters. Benutzernamen gelten nur noch in normalisierter Form, also kleingeschrieben und ohne Leerzeichen am Anfang oder Ende. Zeigt Ihre Installation vorher eine Reparaturmeldung zu nicht normalisierten Benutzernamen, passen Sie die Namen vor dem Update an. Im Test lief das Update von 2026.9.4 auf 2026.10.0 mit der compose.yaml aus Schritt 2 durch, die Anmeldung mit dem zuvor angelegten Konto funktionierte danach.

Backup anlegen

Seit Version 2025.1 gibt es die integrierten Backups unter Einstellungen > System > Backups auch in der Container-Variante, inklusive Wiederherstellung. Sichern Sie zusätzlich das config-Verzeichnis auf Dateiebene, am besten vor jedem Update, bei kurz gestopptem Container. Da der Container als root schreibt, braucht tar root-Rechte:

docker compose stop homeassistant
sudo tar czf ha-backup-$(date +%F).tar.gz config
docker compose start homeassistant

Bewahren Sie die Archive außerhalb des Servers auf (z. B. NAS oder Offsite-Storage). Zur Wiederherstellung spielen Sie config zurück und starten den Stack neu.

Verifizieren: tar tzf ha-backup-*.tar.gz | head listet Dateien wie config/configuration.yaml und config/.storage/. Nach dem Update zeigt Einstellungen > Info die neue Version.

Troubleshooting

Die häufigsten Stolpersteine und ihre Lösung:

Häufige Fragen

Was ist der Unterschied zwischen Home Assistant Container und HAOS?

HAOS bringt den Supervisor mit Ein-Klick-Add-ons und Updates per Klick. Die Container-Variante ist schlanker; Add-on-Ersatz und Updates organisieren Sie selbst, die integrierten Backups gibt es in beiden. Mit vorhandenem Docker-Host ist der Container oft die flexiblere Wahl.

Brauche ich eine GPU für Home Assistant?

Nein. Nur rechenintensive Zusatzdienste in eigenen Containern (lokales LLM-Serving, Bildgenerierung/-erkennung) profitieren von GPU plus nvidia-container-toolkit.

Wie aktualisiere ich Home Assistant im Container?

docker compose pull homeassistant zieht das Image, docker compose up -d ersetzt den Container. Vorher Release Notes prüfen und config sichern (Schritt 7).

Kann ich Mosquitto, Zigbee2MQTT oder ESPHome trotzdem nutzen?

Ja, als separate Docker-Container, die Sie über das Netzwerk anbinden (z. B. MQTT-Broker als Container, in Home Assistant die MQTT-Integration).

Warum funktioniert die Geräteerkennung nicht?

Fast immer fehlt network_mode: host; mDNS, SSDP und UPnP brauchen direkten Zugriff auf das Host-Netz. Ohne Host-Netz geben Sie Port 8123 frei und fügen Integrationen manuell hinzu.

Wie sichere ich meine Installation?

Mit den integrierten Backups unter Einstellungen > System > Backups und zusätzlich einem Archiv des config-Verzeichnisses bei gestopptem Container, abgelegt außerhalb des Servers (Schritt 7).

Fazit

Home Assistant Container liefert eine lokale Smart-Home-Zentrale ohne Cloud-Abhängigkeit als nachvollziehbaren Docker-Stack. Die Flexibilität kostet an zwei Stellen: Add-ons ersetzen Sie durch eigene Container, Updates organisieren Sie selbst; mit den gezeigten Befehlen ist beides Routine.

Weiterführende Anleitungen und Quellen

1. Docker Compose Grundlagen: Stacks sauber aufbauen und betreiben
2. Docker-Netzwerke und Volumes verstehen (Host-Netz, Persistenz)
3. Pi-hole als Werbeblocker und DNS mit Docker einrichten
4. Weitere Hardware- und Server-Anleitungen in unserer Kategorie Hardware

Quellen:

1. Home Assistant - Alternative installation methods (Container, offizielles compose.yaml & docker run)
2. Home Assistant - Common tasks (Container): Update, Backup, check_config
3. Home Assistant - Installation (Vergleich Container vs HAOS, Feature-Tabelle)
4. Home Assistant - HTTP integration (Reverse-Proxy: use_x_forwarded_for, trusted_proxies)