Home Assistant Docker installieren: Compose statt HA OS

Die Doku von Home Assistant empfiehlt für die meisten Leute das eigene Betriebssystem, Home Assistant OS. Und trotzdem tippt kaum jemand „home assistant os" bei Google ein, sondern „home assistant docker installieren". Ich glaube, ich weiß, warum: Wer schon einen Server mit Docker hat, will keinen zweiten Rechner, keine zweite Platte und keine zweite Verwaltung. Er will einen Container mehr, neben Jellyfin, Immich und dem Rest. Das geht, die Doku beschreibt es sauber, und es kostet etwas, das ich dir vorher sage, nicht nachher.

Docker oder Home Assistant OS: was du mit dem Container aufgibst

Home Assistant ist die Schaltzentrale fürs Smart Home: Lampen, Steckdosen, Thermostate, Sensoren, egal von welchem Hersteller, landen in einer Oberfläche und lassen sich miteinander verknüpfen. „Wenn die Haustür aufgeht und es dunkel ist, Flurlicht an" ist dort ein Klick-Dialog, keine Programmierung. Das Projekt ist Open Source, läuft komplett im eigenen Netz und spricht mit weit über tausend Integrationen. Die Installation gibt es in zwei Formen, und die Doku ist ehrlich, welche sie bevorzugt.

Das ist der Preis, und er steht so in der Installationsübersicht: Container-Installationen haben keinen Zugriff auf Apps, und Thread und Z-Wave, die über solche Apps laufen, sind darum nicht von Haus aus dabei. Alles, was du sonst per App aus dem Katalog holen würdest, betreibst du als eigenen Container daneben. Für jemanden, der ohnehin Docker Compose schreibt, ist das kein Verlust, sondern die normale Arbeitsweise: Der MQTT-Broker ist dann ein Dienst in derselben Compose-Datei, nicht ein Menüpunkt. Für jemanden, der zum ersten Mal einen Server anfasst, ist Home Assistant OS der bessere Weg, und das sage ich, obwohl dieser Beitrag den anderen beschreibt.

Mein Urteil für die Zielgruppe hier: Läuft bei dir schon ein Docker-Host, nimm den Container. Du behältst eine Maschine, ein Backup-Konzept und eine Stelle, an der du nachsiehst, wenn etwas klemmt. Willst du Zigbee oder Z-Wave, geht das auch im Container, nur eben mit einem USB-Stick, den du durchreichst, und darauf kommen wir in Schritt 4.

Das Schaubild zeigt den Grund für die auffälligste Zeile in der Compose-Datei: Home Assistant hängt nicht hinter Dockers eigenem Netz, sondern direkt im Heimnetz. Viele Geräte melden sich per Rundruf (mDNS, SSDP), und ein Rundruf kommt durch Dockers Brücke nicht durch. Darum network_mode: host. Das sorgt gleich für den Moment, in dem Home Assistant Geräte findet, von denen du vergessen hattest, dass du sie besitzt.

Was du brauchst

• Einen Linux-Server mit Docker, laut Doku mindestens Docker Engine 23.0. Docker Desktop wird ausdrücklich nicht unterstützt, und dasselbe gilt für Windows und macOS als Host: Ohne Host-Netz findet Home Assistant dort nichts.
• Docker Compose als Plugin, also der Befehl docker compose mit Leerzeichen. Wenn dir das Werkzeug neu ist: die Compose-Grundlagen erklären Datei und Befehle in Ruhe.
• Port 8123 frei auf dem Server. Mit Host-Netz gibt es kein Umbiegen des Ports in der Compose-Datei; Home Assistant nimmt sich 8123 direkt.
• Etwa 2 GB Platz für Image und Konfiguration, Luft nach oben für die Datenbank, die mit jedem Sensor wächst.
• Optional: einen Zigbee-Stick, wenn du Zigbee-Geräte hast. Ohne Stick überspringst du Schritt 4.

Zwei Prüfbefehle, bevor du anfängst. Der erste zeigt die Docker-Version, der zweite, ob 8123 schon belegt ist.

docker --version && docker compose version
ss -tlnp | grep ':8123 ' || echo "Port frei"

Die erste Zeile muss zwei Versionen liefern, Docker ab 23 und ein Compose mit v2 oder höher. Die zweite endet mit „Port frei". Steht dort stattdessen ein Prozess, läuft schon etwas auf 8123; wie du den Schuldigen findest, steht im eigenen Beitrag.

Schritt 1: Ordner und Compose-Datei anlegen

Erst der Ordner, dann die Datei. Der Unterordner config entsteht beim ersten Start von selbst, du musst ihn nicht anlegen.

mkdir -p ~/homeassistant && cd ~/homeassistant
nano compose.yaml

In den leeren Editor kommt dieser Inhalt. Es ist die Compose-Datei aus der offiziellen Linux-Installationsseite, mit drei Anpassungen: dem festen Versions-Tag, dem Pfad ./config statt des Platzhalters und der Zeitzone. Speichern mit Strg+O, Enter, schließen mit Strg+X.

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:2026.10.1"
    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 Zeilen tun, damit du sie nicht nur kopierst:

• image: Die Doku schreibt :stable. Ich schreibe die Version hin, weil Home Assistant jeden Monat ein Release mit eigenen „Backward-incompatible changes" bringt, und die liest man lieber, bevor sie einen treffen. Beim Update änderst du die Zahl bewusst, statt sie beim nächsten pull nebenbei zu bekommen.
• ./config:/config: Hier liegt alles, was du jemals einrichtest: Benutzer, Geräte, Automationen, die Datenbank mit der Historie. Ohne diese Zeile wäre nach jedem Neubau des Containers alles weg. Diese Zeile ist die, die du später sicherst.
• /etc/localtime und TZ: Zweimal Uhrzeit, mit Absicht. Die Datei gibt dem Container die Zeit des Servers, die Variable sagt Home Assistant, welche Zeitzone gemeint ist. Eine Automation „um 7 Uhr" ist sonst eine Automation „um 7 Uhr UTC", und das merkt man im Winter zuerst.
• /run/dbus: Laut Doku optional und nur für die Bluetooth-Integration nötig. Sie schadet nicht, also bleibt sie drin; auf einem Server ohne Bluetooth tut sie schlicht nichts.
• stop_grace_period: 60s: Beim Stoppen bekommt Home Assistant eine Minute, um die Datenbank sauber zu schließen, statt der üblichen zehn Sekunden. Das ist der Unterschied zwischen einem sauberen Neustart und einer kaputten Historie.
• privileged: true: Die Zeile, die mir am wenigsten gefällt, und sie steht so in der Doku. Sie gibt dem Container fast die Rechte des Servers, damit USB-Sticks und Bluetooth ohne Nacharbeit funktionieren. Für den reinen Start brauchst du sie nicht; ich lasse sie drin, weil die Doku es tut und weil der Stick in Schritt 4 sonst der häufigste Grund für „sieht meinen Stick nicht" wird. Nach außen offen ist der Container dadurch nicht; was er darf, darf er auf deinem Server.
• network_mode: host: Kein eigener ports:-Abschnitt, weil der Container das Netz des Servers direkt benutzt. Dafür findet Home Assistant Geräte per Rundruf, dafür ist der Port fest 8123.

Schritt 2: Container starten und prüfen

docker compose up -d

Das Image ist rund 700 MB groß, der erste Pull dauert je nach Leitung eine Minute oder fünf. Danach braucht Home Assistant selbst noch einen Moment, bis es antwortet. Erst der Blick auf den Container, dann der Klopftest auf den Port.

docker compose ps
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8123/

NAME            IMAGE                                             COMMAND   SERVICE         CREATED                  STATUS                  PORTS
homeassistant   ghcr.io/home-assistant/home-assistant:2026.10.1   "/init"   homeassistant   Less than a second ago   Up Less than a second
302

Die 302 ist das gute Zeichen: Home Assistant antwortet und schickt dich zur Einrichtungsseite weiter. Kommt stattdessen eine 000, ist es noch nicht so weit; zwanzig Sekunden warten und noch einmal klopfen. Bleibt es dabei, zeigen die Logs, woran es hängt:

docker compose logs --tail 50 homeassistant

Und ein Blick auf die Platte, denn jetzt sollte der Ordner config gefüllt sein:

ls ~/homeassistant/config

automations.yaml  configuration.yaml  home-assistant.log  scenes.yaml  scripts.yaml  secrets.yaml

Im Sandkasten hat das vom ersten Befehl bis zur 302 knapp eine Minute gedauert, Pull inklusive. Das ging mir zu glatt, also habe ich zweimal hingesehen. Es stimmte beide Male.

Schritt 3: Zuhause einrichten

Jetzt der Browser, auf irgendeinem Rechner im selben Netz. Die Adresse ist die IP deines Servers mit dem Port; homeassistant.local aus der Doku funktioniert beim Container meist nicht, weil dieser Name von Home Assistant OS kommt.

Was du jetzt siehst, ist die Übersicht, und sie ist nicht leer. Home Assistant hat schon beim Start ins Netz gehorcht. Links unten hängt an Einstellungen eine Zahl: so viele Geräte hat es gefunden, Fernseher, Drucker, Router, Spotify-Lautsprecher, was eben antwortet. Das ist der Moment, für den die Zeile network_mode: host da war. Kurz freuen ist erlaubt.

Die Knöpfe der Einrichtung habe ich so genannt, wie die Doku sie nennt, auf Englisch; spricht dein Browser Deutsch, stehen sie bei dir übersetzt da. Die Sprache stellst du später im eigenen Profil um, unten links auf den Benutzernamen.

Schritt 4: Zigbee-Stick durchreichen (optional)

Zigbee-Lampen und -Sensoren sprechen nicht WLAN, sondern ein eigenes Funknetz, und dafür braucht der Server eine Antenne: einen USB-Stick. Im Container ist der Stick erst da, wenn du ihn in der Compose-Datei durchreichst. Vorher musst du wissen, wie er heißt.

ls /dev/serial/by-id/

usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_abc123-if00-port0

Bei dir steht ein anderer Name, mit deinem Hersteller und deiner Seriennummer. Nimm diesen Pfad und nicht /dev/ttyUSB0, auch wenn die ZHA-Doku im Beispiel das Kurze zeigt: Die Doku selbst empfiehlt den Pfad aus /dev/serial/by-id, weil die Nummer hinter ttyUSB nach einem Neustart eine andere sein kann, der Name mit der Seriennummer nicht. In ~/homeassistant/compose.yaml im Dienst homeassistant kommen auf Höhe von volumes diese zwei Zeilen dazu:

    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_abc123-if00-port0:/dev/ttyUSB0

Links der lange Name vom Server, rechts der kurze Name, unter dem der Stick im Container erscheint. Dann den Container neu bauen, damit er den Stick bekommt, und nachsehen, ob er drin ist:

docker compose up -d
docker exec homeassistant ls /dev/ttyUSB0

/dev/ttyUSB0

Danach in der Oberfläche die Integration anlegen:

Was am Ende eingestellt ist

• Ein Benutzer, und der ist Eigentümer. Weitere Personen bekommen eigene Konten unter Einstellungen → Personen, und nicht jede davon muss Administrator sein. Das Eigentümer-Passwort liegt im Passwort-Manager, weil es keinen „Passwort vergessen"-Weg gibt.
• Alles liegt in ~/homeassistant/config. Benutzer, Geräte, Automationen, Datenbank. Die Rechte an den Dateien gehören root, weil der Container als root läuft; zum Lesen reicht dein Benutzer, zum Ändern mit nano brauchst du sudo.
• Backups laufen in der Oberfläche, auch im Container: Seit Release 2025.1 gilt das Backup-System für alle Installationsarten. Unter Einstellungen → System → Backups legst du eine Sicherung an und planst sie täglich; dabei zeigt dir Home Assistant einen Verschlüsselungsschlüssel, ohne den sich die Sicherung nicht zurückspielen lässt. Herunterladen, zum Eigentümer-Passwort legen. Die Datei landet im config-Ordner, also auf dem Server, dessen Ausfall sie abfangen soll; wohin sie von dort wandert, ist dieselbe Frage wie bei jedem anderen Container-Backup. Prüfen, dass sie da ist: find ~/homeassistant/config -name "*.tar".
• Updates machst du selbst. Einmal im Monat kommt ein Release, am ersten Mittwoch. Vorher die Release-Notes nach „Backward-incompatible changes" absuchen, dann die Version in der Compose-Datei ändern und docker compose pull homeassistant && docker compose up -d. Die Doku rät vor jedem Update zum Backup, und ich auch, du kennst das.
• Unverschlüsselt im Heimnetz. Port 8123 ist HTTP ohne HTTPS. Im eigenen WLAN ist das in Ordnung; von unterwegs erreichst du Home Assistant über ein VPN ins Heimnetz oder einen Reverse Proxy mit Zertifikat, nie über eine nackte Portfreigabe. Die Handy-App übrigens auch: Sie braucht nur die Adresse, die du im Browser benutzt.

Wo es erfahrungsgemäß klemmt

Keine Geräte entdeckt. Fast immer fehlt network_mode: host, oder jemand hat stattdessen einen ports:-Abschnitt eingebaut, weil er den Port verlegen wollte. Mit Brücken-Netz läuft Home Assistant, findet aber nichts von selbst, und einige Integrationen scheitern leise. Der Port lässt sich im Host-Netz nicht verlegen; wenn 8123 belegt ist, muss der andere Dienst weichen, nicht Home Assistant.

Der Stick ist im Container nicht da. Erst auf dem Server prüfen, nicht im Container: Zeigt ls /dev/serial/by-id/ nichts, ist das Problem der Server, nicht Docker. Zeigt es den Stick, aber im Container fehlt er, wurde nach dem Eintragen der devices-Zeilen nur restart statt up -d gemacht. Ein Neustart liest die Compose-Datei nicht neu; nur up -d baut den Container mit dem Stick.

ZHA startet nach einem Neustart nicht. Die ZHA-Doku nennt die Ursache: Der Dienst modemmanager auf dem Server hält den Stick für ein Modem und belegt ihn. Ihre Lösung auf Debian und Ubuntu ist, den Dienst zu entfernen, mit sudo apt-get purge modemmanager. Auf einem Server ohne Mobilfunkmodem verliert man damit nichts.

Die App aus dem Katalog fehlt. Das ist kein Fehler, das ist Schritt eins dieses Beitrags. Mosquitto als MQTT-Broker, Zigbee2MQTT, ein Datei-Editor: alles eigene Container, meist in derselben Compose-Datei. Wer aus Anleitungen für Home Assistant OS kopiert, sucht den Apps-Katalog vergeblich; die Container-Variante dieser Anleitungen gibt es fast immer, nur unter dem Namen des jeweiligen Projekts.

Was läuft jetzt eigentlich? Ein Dienst, der dein Zuhause versteht, auf einer Platte, die dir gehört, ohne ein Konto beim Hersteller der Lampe. Die erste Automation ist nicht Teil dieses Beitrags, aber sie ist der Grund, warum du ihn gelesen hast: Einstellungen → Automationen & Szenen, und dort findest du dich zurecht, versprochen.

Was hat dich zu Home Assistant gebracht, die eine Lampe, die ohne Cloud nicht mehr anging, oder der Stromzähler? Und läuft es bei dir im Container oder als OS? Schreib's in die Kommentare.

Der nächste Schritt für viele ist Zigbee ohne Herstellerbrücke, und dafür lohnt sich ein eigener Beitrag zu Zigbee2MQTT neben Home Assistant. Wer ihn nicht verpassen will, holt sich den Newsletter; der sagt Bescheid, wenn er da ist.

Quellen

• Home Assistant: Installation auf Linux, Abschnitt Home Assistant Container (Compose-Datei, Voraussetzungen, USB-Geräte)
• Home Assistant: Installationsarten im Vergleich (OS gegen Container, keine Apps im Container)
• Home Assistant: Onboarding (erstes Konto, Standort, Datenfreigabe)
• Home Assistant: Common tasks für Container (Update per Compose, Konfigurationsprüfung)
• Home Assistant: Backups anlegen und planen
• Home Assistant: Integration Zigbee Home Automation (ZHA), Docker-Hinweise und modemmanager
• Home Assistant 2025.1: Backups für alle Installationsarten
• Home Assistant 2026.10: Release-Blog mit Backward-incompatible changes
• Home Assistant Core: Releases auf GitHub (2026.10.1)