Mit Docker lässt sich Home Assistant zusammen mit dem MQTT-Broker Mosquitto auf einem Ubuntu-Server schnell, sauber und isoliert betreiben. Diese Anleitung führt Schritt für Schritt durch die Installation unter /home/homeassistant/docker.

Docker installieren

Falls Docker auf dem Ubuntu-System noch nicht eingerichtet ist, lässt es sich über das offizielle Repository installieren:

# Paketlisten aktualisieren und Voraussetzungen installieren
sudo apt update && sudo apt install -y ca-certificates curl gnupg lsb-release

# Offiziellen Docker GPG-Schlüssel hinzufügen
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Repository einrichten
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker Engine & Compose Plugin installieren
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Aktuellen Benutzer zur docker-Gruppe hinzufügen (vermeidet sudo bei Docker-Befehlen)
sudo usermod -aG docker $USER
newgrp docker

Verzeichnisstruktur und Mosquitto-Konfiguration erstellen

Erstellen Sie die benötigten Ordner für die persistenten Daten von Home Assistant und Mosquitto:

sudo mkdir -p /home/homeassistant/docker/config
sudo mkdir -p /home/homeassistant/docker/mosquitto/config \
              /home/homeassistant/docker/mosquitto/data \
              /home/homeassistant/docker/mosquitto/log

# D-Bus Verzeichnis auf dem Host sicherstellen (wird von Home Assistant genutzt)
sudo mkdir -p /run/dbus

# Besitzrechte für das Arbeitsverzeichnis an den aktuellen Benutzer übertragen
sudo chown -R $USER:$USER /home/homeassistant/docker

cd /home/homeassistant/docker

Die Configdatei „mosquitto/config/mosquitto.conf“ für Mosquitto erstellen, und mit folgenden Code befüllen:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwords
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

Schreibrechte anpassen:

sudo chown -R 1883:1883 /home/homeassistant/docker/mosquitto

Docker Compose einrichten und Container starten

Anlegen der Datei „docker-compose.yml“ mit folgendem Inhalt:

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

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:latest
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - /home/homeassistant/docker/mosquitto/config:/mosquitto/config
      - /home/homeassistant/docker/mosquitto/data:/mosquitto/data
      - /home/homeassistant/docker/mosquitto/log:/mosquitto/log

MQTT-Benutzer anlegen & Stack starten

Wechselne in das Arbeitsverzeichnis und starte zuerst ausschließlich den Mosquitto-Container, um den MQTT-Benutzer anzulegen:

cd /home/homeassistant/docker
docker compose up -d mosquitto

Legen nun den Benutzer für die MQTT-Geräte und Home Assistant an (z. B. homeassistant). Verwende bewusst nicht den Parameter -c, damit bestehende Konfigurationen nicht überschrieben werden:

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwords homeassistant

Sichere die Dateirechte der neu erstellten Passwort-Datei ab, um Warnungen und Berechtigungsfehler im Mosquitto-Log zu vermeiden:

sudo chmod 600 /home/homeassistant/docker/mosquitto/config/passwords
sudo chown 1883:1883 /home/homeassistant/docker/mosquitto/config/passwords

Und anschließend den gesamten Stack starten:

docker compose up -d

Home Assistant Ersteinrichtung & MQTT-Integration

Öffne im Browser http://<IP-DEINES-SERVERS>:8123.
Erstelle das Administrator-Konto und schließe die Ersteinrichtung ab.
- Erstellen eines Admin Kontos
- Wählen des Standortes
- Erlaubnis zum Teile anonymisierte Daten
Navigiere zu Einstellungen → Geräte & Dienste → Integration hinzufügen.
Suchen nach MQTT und wählen Sie es aus.
Trage die Verbindungsdaten ein:
- Broker: localhost (oder die IP-Adresse des Ubuntu-Servers)
- Port: 1883
- Benutzername: homeassistant
- Passwort: Das in Schritt 4 vergebene Passwort

MQTT-Benutzer ändern und hinzufügen

Im Smart Home ist es ratsam, verschiedenen Geräten eigene Zugangsdaten zuzuweisen oder Passwörter bei Bedarf anzupassen. Der Mosquitto-Broker erlaubt das Anlegen mehrerer Benutzer sowie das Ändern bestehender Passwörter.

Weitere Benutzer hinzufügen

Um einen neuen Benutzer (z. B. tasmota für deine Steckdosen) anzulegen, führe folgenden Befehl aus:

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwords tasmota

Passwörter bestehender Benutzer ändern

Das Ändern eines Passworts für einen bereits existierenden Benutzer (z. B. homeassistant) erfolgt mit demselben Befehl:

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwords homeassistant

Dateirechte absichern & Mosquitto neu starten

Nach jedem Erstellen oder Ändern von Benutzern solltest du die Rechte der Passwort-Datei erneut absichern und den Container neu starten, damit Mosquitto die Änderungen lädt:

# Rechte der Passwort-Datei sichern
sudo chmod 600 /home/homeassistant/docker/mosquitto/config/passwords
sudo chown 1883:1883 /home/homeassistant/docker/mosquitto/config/passwords

# Mosquitto-Container neu starten
docker restart mosquitto

Warum zwei Docker-Container? Das Zusammenspiel von Home Assistant & Mosquitto

Ein zentrales Prinzip von Docker lautet: Ein Container pro Aufgabe (Single Responsibility Principle). Anstatt alle Smart-Home-Dienste in ein einzelnes, träges System zu packen, teilen wir die Aufgaben auf zwei spezialisierte Container auf.

Die Rollen der beiden Container

Mosquitto (Der Postbote)
- Mosquitto ist ein extrem leichtgewichtiger MQTT-Broker. Seine einzige Aufgabe ist das schnelle, zuverlässige Empfangen und Weiterleiten von Nachrichten im Netzwerk. Er kennt keine Smart-Home-Logiken, Szenen oder Dashboards, sondern nimmt Telegramme von Geräten entgegen und verteilt sie an alle Abonnenten.
Home Assistant (Das Gehirn)
- Home Assistant ist die smarte Schaltzentrale. Hier laufen die Automatisierungen, die Benutzeroberfläche (Dashboard) und die Logik. Home Assistant wertet Sensorwerte aus, führt Zeitpläne aus und steuert deine Geräte.

Wie die Container zusammenarbeiten

Die Kommunikation zwischen den Komponenten folgt dem Publish/Subscribe-Prinzip (Veröffentlichen und Abonnieren):

[ Tasmota-Steckdose ]  ---(1. Schalterzustand senden)--->  [ Mosquitto Broker ]
                                                                  |
                                                    (2. Nachricht weiterleiten)
                                                                  v
[ Dashboard / User ]   <---(3. Status anzeigen)-----------  [ Home Assistant ]

Ein Gerät sendet Daten (Publish): Wenn du beispielsweise eine Tasmota-Steckdose manuell einschaltest, sendet das Gerät eine MQTT-Nachricht (z. B. stat/steckdose1/POWER = ON) an den Mosquitto-Container auf Port 1883.
Mosquitto verteilt die Daten: Mosquitto prüft, wer sich für das Thema (Topic) stat/steckdose1/POWER interessiert.
Home Assistant empfängt Daten (Subscribe): Da Home Assistant über die MQTT-Integration beim Mosquitto-Broker angemeldet ist und das Thema abonniert hat, empfängt es die Nachricht sofort und aktualisiert den Schalterstatus auf dem Dashboard.
Befehle senden (Der umgekehrte Weg): Klickst du in Home Assistant auf „Ausschalten“, schickt Home Assistant eine Nachricht (cmnd/steckdose1/POWER = OFF) an Mosquitto. Mosquitto reicht diesen Befehl an die Steckdose weiter, die daraufhin das Relais öffnet.

Die Vorteile dieser Trennung

Unabhängigkeit
- Wenn Home Assistant z. B. für ein Update neu gestartet wird, läuft der Mosquitto-Broker ununterbrochen weiter. Deine MQTT-Geräte verlieren nie die Verbindung zum Broker und können weiterhin Nachrichten puffern.
Leistung & Stabilität
- Mosquitto ist in C geschrieben, extrem ressourcenschonend und arbeitet hochparallel. Es verbraucht kaum Arbeitsspeicher und entlastet Home Assistant spürbar.
Flexibilität
- Du kannst jederzeit weitere Systeme (wie z. B. Node-RED, eigene Python-Scripte oder WLED-Monitore) an denselben Mosquitto-Broker anbinden, ohne die Konfiguration von Home Assistant anpassen zu müssen.

FAQ

HomeAssistant Admin Passwort vergessen

Um das Passwort des HomeAssistant Admin zu löschen, muss man folgende Schritte durchführen:

auf des Ubuntu-Server einloggen (ssh)
In das Arbeitsverzeichnis wechseln
- cd /home/homeassistant/docker
Home Assistant stoppen
- docker compose stop homeassistant
Auth-Dateien im Config-Ordner sichern & löschen
- Navigiere in den internen .storage-Ordner von Home Assistant. Dort verwaltet Home Assistant die Benutzerkonten:
  - cd /home/homeassistant/docker/config/.storage
- Lösche die Dateien für die Benutzerverwaltung und Authentifizierung (oder benenne sie zur Sicherheit um):
  - sudo mv auth auth.bak
  - sudo mv onboarding onboarding.bak
  - sudo mv auth_provider.homeassistant auth_provider.homeassistant.bak
Home Assistant Container wieder starten
- cd /home/homeassistant/docker
- docker compose start homeassistant
Neuen Admin-Account im Browser anlegen:
- Öffne im Browser erneut http://<IP-DEINES-SERVERS>:8123.
- Home Assistant begrüßt dich nun wieder mit dem Welcome- / Ersteinrichtungs-Bildschirm.
- Erstelle einen neuen Administrator-Benutzer (du kannst denselben Benutzernamen wie vorher verwenden).
- Nach dem Abschließen des Assistenten gelangst du wieder auf dein gewohntes Dashboard. Alle deine Einstellungen, Integrationen, Skripte und Karten sind weiterhin vollständig vorhanden.

Die gesammte Installation als Bash Script: homeassistant_install.sh

Steffens Webseite

HomeAssistant mit Docker einrichten