Home Assistant als Docker-Container installieren¶

Veröffentlicht am 7. August 2026 · Geschätzte Lesezeit: 4 Minuten

Mit Home Assistant steuerst du Geräte verschiedener Hersteller in einer gemeinsamen Oberfläche. Die Container-Variante läuft auf einem vorhandenen Docker-Server und speichert ihre Einstellungen außerhalb des Containers. Für Installation und erste Einrichtung solltest du etwa 20 bis 30 Minuten einplanen.

Voraussetzungen

Ein Linux-Server mit Docker und Docker Compose
Mindestens 2 GB freier Arbeitsspeicher
Eine feste IP-Adresse oder DHCP-Reservierung für den Server
Ein Benutzer mit sudo-Rechten

Container oder Home Assistant OS?

Home Assistant Container enthält keinen App-Store für Erweiterungen. Updates führst du selbst mit Docker aus. Möchtest du Erweiterungen direkt aus Home Assistant installieren, ist Home Assistant OS meist die einfachere Wahl.

1. Arbeitsordner anlegen¶

Führe diesen Befehl im Terminal deines Docker-Servers aus. Er legt den Ordner für die Compose-Datei und alle dauerhaft gespeicherten Einstellungen an.

sudo mkdir -p /opt/homeassistant/config

Wechsle anschließend in den neuen Ordner:

cd /opt/homeassistant

2. Compose-Datei erstellen¶

Lege im Ordner /opt/homeassistant eine Datei namens compose.yaml mit folgendem Inhalt an:

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

Der Ordner /opt/homeassistant/config bleibt beim Austausch des Containers erhalten. Mit network_mode: host kann Home Assistant Geräte im lokalen Netz per mDNS und anderen Verfahren finden. privileged: true gibt dem Container weitreichende Rechte und entspricht der offiziellen Compose-Vorlage.

Nicht direkt ins Internet stellen

Leite Port 8123 nicht einfach im Router weiter. Nutze für den Fernzugriff lieber ein VPN wie Tailscale oder einen korrekt abgesicherten HTTPS-Reverse-Proxy. Der Container besitzt wegen privileged: true umfangreiche Rechte auf dem Host.

3. Container starten¶

Starte Home Assistant im Hintergrund. Führe den Befehl im Ordner /opt/homeassistant aus:

docker compose up -d

Prüfe danach, ob der Container läuft:

docker compose ps

Bei Problemen zeigen die letzten Protokollzeilen meist die Ursache:

docker compose logs --tail=100 homeassistant

4. Ersteinrichtung abschließen¶

Öffne im Browser die folgende Adresse:

http://<server-ip>:8123

Ersetze <server-ip> durch die IP-Adresse deines Docker-Servers, zum Beispiel 192.168.178.20. Die erste Initialisierung kann einige Minuten dauern. Lege danach dein Administratorkonto mit einem langen, einzigartigen Passwort an und prüfe Standort, Zeitzone sowie Einheitensystem.

Automatisch gefundene Geräte

Home Assistant zeigt erkannte Geräte und Dienste meist unter Einstellungen → Geräte & Dienste an. Füge zunächst nur ein Gerät hinzu und teste es, bevor du weitere Integrationen einrichtest.

5. USB-Gerät bei Bedarf durchreichen¶

Dieser Schritt ist nur nötig, wenn Home Assistant direkt auf einen USB-Stick zugreifen soll. Ermittle zuerst im Terminal den stabilen Gerätepfad:

ls -l /dev/serial/by-id/

Ergänze danach im Dienst homeassistant der compose.yaml den folgenden Abschnitt. Ersetze <geraete-id> durch den vollständigen Namen aus der vorherigen Ausgabe:

    devices:
      - /dev/serial/by-id/<geraete-id>:/dev/ttyUSB0

Übernimm die Änderung anschließend:

docker compose up -d

Gerätepfad nicht raten

Verwende möglichst /dev/serial/by-id/... statt /dev/ttyUSB0. Die kurze Bezeichnung kann sich nach einem Neustart ändern. Ein falscher Pfad verhindert den Start des Containers.

6. Sicherung erstellen¶

Beende Home Assistant kurz, damit sich während der Sicherung keine Dateien ändern:

cd /opt/homeassistant
docker compose stop

Packe den kompletten Konfigurationsordner in ein Archiv. Das Archiv landet im Home-Verzeichnis des angemeldeten Benutzers und enthält auch sensible Schlüssel:

sudo tar -czf "$HOME/homeassistant-config-$(date +%F).tar.gz" config

Starte Home Assistant danach wieder:

docker compose start

Sicherung vertraulich behandeln

Im Ordner config können Kennwörter, Zugriffsschlüssel und Standortdaten liegen. Kopiere das Archiv verschlüsselt auf ein zweites Speichermedium und veröffentliche es niemals.

Zum Rückweg stoppst du den Container, benennst den defekten Ordner config um und entpackst dort dein Sicherungsarchiv. So bleibt der bisherige Stand erhalten, falls du ihn noch einmal untersuchen möchtest.

7. Home Assistant aktualisieren¶

Erstelle vor jedem größeren Update eine Sicherung und lies die Hinweise zur neuen Version. Lade danach das aktuelle stabile Image:

cd /opt/homeassistant
docker compose pull

Ersetze den laufenden Container durch die neue Version:

docker compose up -d

Nicht mehr benötigte Images kannst du später entfernen:

docker image prune

8. Typische Fehler beheben¶

Ist die Oberfläche nicht erreichbar, kontrolliere zuerst Container und Protokoll:

docker compose ps
docker compose logs --tail=100 homeassistant

Prüfe anschließend, ob Port 8123 auf dem Server lauscht:

sudo ss -lntp | grep 8123

Fehlt ein USB-Gerät, kontrolliere den Pfad erneut. Bei Fehlern mit dbus prüfst du, ob /run/dbus auf deinem Linux-Server vorhanden ist. Ist das nicht der Fall und du benötigst kein Bluetooth, kannst du diese Volume-Zeile aus der Compose-Datei entfernen.

9. Quellen und Video¶

Fertig¶

Home Assistant läuft jetzt als Docker-Container und speichert seine Daten dauerhaft unter /opt/homeassistant/config. Öffne http://<server-ip>:8123, melde dich an und schalte ein hinzugefügtes Gerät einmal ein und aus. Reagiert es sofort, funktioniert die Grundinstallation.