Home Assistant auf Raspberry Pi mit Docker: Installation und Grundeinrichtung

Home Assistant auf dem Raspberry Pi: Dein Smart Home zentral steuern

Du hast TAPO Kameras, Philips Hue Lampen und Homematic IP Thermostate - aber drei verschiedene Apps? Home Assistant vereint alle deine Smart Home Geräte in einer einzigen Oberfläche. In dieser Anleitung zeige ich dir, wie du Home Assistant als Docker Container auf deinem Raspberry Pi installierst. So läuft es problemlos neben deinen anderen Containern wie Traefik, Grafana oder InfluxDB.

DarkWolfCave.de

Warum Home Assistant?

Wenn du wie ich verschiedene Smart Home Systeme nutzt, kennst du das Problem: Für jedes System eine eigene App. TAPO hier, Hue da, Homematic IP dort. Home Assistant löst dieses Problem, indem es alle Systeme unter einer Oberfläche vereint.

Die Vorteile auf einen Blick

• Zentrale Steuerung - Alle Smart Home Geräte in einer App
• Lokal statt Cloud - Deine Daten bleiben bei dir (Datenschutz!)
• 2000+ Integrationen - Praktisch jedes Smart Home System wird unterstützt
• Automatisierungen - Wenn Fenster offen, dann Heizung aus
• Kostenfrei und Open Source - Keine Abo-Gebühren

Smart Home Protokolle verstehen

Bevor wir loslegen, ein kurzer Überblick über die verschiedenen Funkprotokolle im Smart Home. Das hilft dir zu verstehen, welche Hardware du wirklich brauchst.

WiFi-Geräte (TAPO, Shelly, etc.)

• Verbinden sich direkt mit deinem WLAN-Router
• Brauchen keinen extra Hub
• Home Assistant steuert sie über die Cloud-API oder lokal
• Beispiele: TAPO Kameras, Shelly Steckdosen, WLED

Zigbee (Hue, IKEA, Aqara, etc.)

Zigbee ist ein eigenes Funkprotokoll - nicht WiFi! Es ist stromsparender und bildet ein Mesh-Netzwerk (Geräte leiten Signale weiter).

Das Problem: Normalerweise braucht jeder Hersteller seinen eigenen Hub:

• Philips → Hue Bridge
• IKEA → Tradfri Gateway
• Aqara → Aqara Hub
• Tuya → Tuya Gateway

Die Lösung: Zigbee USB-Dongle

Mit einem Zigbee USB-Dongle am Raspberry Pi ersetzt du alle diese Hubs:

• Ein Stick für alle Zigbee-Geräte
• Geräte verschiedener Hersteller mischen
• Kein Cloud-Zwang, komplett lokal
• Home Assistant steuert direkt via ZHA (eingebaut) oder Zigbee2MQTT (mehr Geräte)

Homematic IP

Homematic IP ist ein eigenes Protokoll - weder WiFi noch Zigbee! Der Zigbee-Dongle hilft hier nicht.

Für Homematic IP brauchst du weiterhin:

• Homematic IP Access Point (Cloud-Variante)
• ODER CCU3/RaspberryMatic (lokale Variante)

Übersicht: Was brauche ich wofür?

Tipp für Einsteiger: Starte mit den vorhandenen Hubs (Hue Bridge, etc.) und der jeweiligen Home Assistant Integration. Den Zigbee-Dongle kannst du später nachrüsten, wenn du alle Hubs durch einen Stick ersetzen willst.

Home Assistant Varianten - Welche ist die Richtige?

Es gibt verschiedene Wege, Home Assistant zu installieren:

Unsere Wahl: Home Assistant Container

Da wir bereits Docker nutzen (für Traefik, Grafana, etc.), ist die Container-Variante ideal. Home Assistant läuft dann einfach als weiterer Container neben deinen bestehenden Diensten.

Systemvoraussetzungen

Hardware

Für Home Assistant mit mehreren Integrationen empfehle ich:

• Raspberry Pi 5 mit 8GB RAM (empfohlen) oder Raspberry Pi 4 mit mindestens 4GB RAM
• NVMe SSD - Smart Home braucht schnellen und zuverlässigen Speicher
• Netzteil 27W für stabilen Betrieb
• Optional: Sonoff Zigbee 3.0 USB Dongle für direkte Geräte-Steuerung ohne Bridge

Software

• Raspberry Pi OS 64-Bit (Bookworm oder neuer)
• Docker und Docker Compose installiert (siehe Docker Installation)
• SSH-Zugriff auf deinen Raspberry Pi
• Optional: Traefik Reverse Proxy (siehe Traefik Anleitung)

Kenntnisse

• Grundlegende Linux-Befehle
• Erfahrung mit Docker und docker-compose.yml
• Dein Smart Home System sollte bereits eingerichtet sein (TAPO App, Hue App, etc.)

Installation mit Docker Compose

Wichtig: Alle folgenden Befehle werden auf dem Raspberry Pi ausgeführt - nicht auf deinem PC oder Mac!

Verbinde dich per SSH mit deinem Raspberry Pi:

ssh pi@raspberry-ip

Ersetze raspberry-ip durch die IP-Adresse deines Pis (z.B. 192.168.1.100). Falls du den Benutzernamen geändert hast, verwende diesen statt pi.

Verzeichnisstruktur erstellen

Jetzt auf dem Pi - lege die Ordnerstruktur für Home Assistant an:

mkdir -p ~/docker/home-assistant/config
cd ~/docker/home-assistant

Docker Compose Datei erstellen

Erstelle die docker-compose.yml Datei:

nano docker-compose.yml

Füge folgenden Inhalt ein (in nano: mit Rechtsklick einfügen, dann Strg+O zum Speichern, Strg+X zum Beenden):

# docker-compose.yml
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      - TZ=Europe/Berlin
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro

Wichtige Erklärungen:

Alternative: Mit Traefik Reverse Proxy

Wenn du Traefik nutzt und Home Assistant über eine Domain erreichen willst:

- "traefik.http.routers.homeassistant.entrypoints=websecure"
- "traefik.http.routers.homeassistant.tls.certresolver=letsencrypt"
+ "traefik.http.routers.homeassistant.entrypoints=web"

# docker-compose.yml mit Traefik
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    privileged: true
    networks:
      - traefik_network
    environment:
      - TZ=Europe/Berlin
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homeassistant.rule=Host(`home.deine-domain.de`)"
      - "traefik.http.routers.homeassistant.entrypoints=websecure"
      - "traefik.http.routers.homeassistant.tls.certresolver=letsencrypt"
      - "traefik.http.services.homeassistant.loadbalancer.server.port=8123"

networks:
  traefik_network:
    external: true

Wichtiger Hinweis zur Traefik-Variante: Ohne network_mode: host funktioniert die automatische Geräte-Erkennung (mDNS/SSDP) nicht. Das bedeutet:

• Home Assistant findet Hue Bridge, TAPO Kameras etc. nicht automatisch
• Du musst beim Einrichten der Integrationen die IP-Adresse des Geräts manuell eingeben
• Die IP findest du in deinem Router unter “Verbundene Geräte” oder in der jeweiligen Hersteller-App

Beispiel: Beim Hinzufügen der Hue Bridge in Home Assistant wirst du nach der IP gefragt (z.B. 192.168.1.50) statt dass sie automatisch erkannt wird.

Container starten

cd ~/docker/home-assistant
docker compose up -d

Prüfe die Logs, ob alles sauber startet:

docker logs -f homeassistant

Nach etwa 1-2 Minuten solltest du sehen:

INFO (MainThread) [homeassistant.core] Starting Home Assistant

Erste Einrichtung

Web-Interface aufrufen

Öffne in deinem Browser:

• Direkt: http://raspberry-ip:8123
• Mit Traefik: https://home.deine-domain.de

Du siehst den Einrichtungsassistenten:

Schritt 1: Benutzer anlegen

• Name: Dein Anzeigename
• Benutzername: Für den Login
• Passwort: Wähle ein sicheres Passwort!

Schritt 2: Standort konfigurieren

• Adresse: Für Wetter und Sonnenauf-/untergang
• Zeitzone: Europe/Berlin
• Einheitensystem: Metrisch
• Währung: EUR

Schritt 3: Erste Geräte

Home Assistant erkennt automatisch viele Geräte in deinem Netzwerk. Du siehst eventuell bereits:

• Philips Hue Bridge
• Drucker
• Smart TVs
• etc.

Tipp: Füge jetzt noch nicht alle Geräte hinzu. Wir machen das systematisch im nächsten Artikel.

Wichtige Basis-Konfiguration

configuration.yaml verstehen

Die Hauptkonfiguration liegt auf dem Pi in ~/docker/home-assistant/config/configuration.yaml.

Warum ist das persistent? Durch das Volume-Mount in der docker-compose.yml (./config:/config) werden alle Konfigurationsdateien auf dem Pi gespeichert, nicht im Container. Der Container kann gelöscht und neu erstellt werden - deine Einstellungen bleiben erhalten.

Du kannst die Datei mit nano bearbeiten:

nano ~/docker/home-assistant/config/configuration.yaml

Beispiel für typische Einstellungen:

# configuration.yaml
homeassistant:
  name: "DarkWolf Smart Home"
  unit_system: metric
  time_zone: Europe/Berlin
  currency: EUR

# Logger auf Warning setzen (spart Ressourcen)
logger:
  default: warning
  logs:
    homeassistant.components.http: warning

Für Traefik/Reverse Proxy

Wenn du einen Reverse Proxy wie Traefik nutzt, muss Home Assistant wissen, welchen Anfragen es vertrauen darf. Füge hinzu:

# configuration.yaml
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.18.0.0/16

Was bedeutet 172.18.0.0/16? Das ist der IP-Bereich des Docker-Netzwerks, in dem Traefik läuft. Docker erstellt interne Netzwerke mit solchen Adressen - das hat nichts mit deinem Heimnetzwerk (192.168.x.x) zu tun.

Dein Docker-Netzwerk finden:

# Zeigt alle Docker-Netzwerke mit ihren IP-Bereichen
docker network inspect traefik_network | grep Subnet

Falls dort z.B. 172.20.0.0/16 steht, verwende diesen Wert statt 172.18.0.0/16.

secrets.yaml für sensible Daten

Erstelle auf dem Pi eine Datei für sensible Daten:

nano ~/docker/home-assistant/config/secrets.yaml

Beispielinhalt:

# secrets.yaml - NIEMALS in Git committen!
hue_bridge_token: "dein-hue-token"
tapo_password: "dein-tapo-passwort"
homematic_password: "dein-homematic-passwort"

Verwendung in configuration.yaml:

some_integration:
  password: !secret tapo_password

Home Assistant neustarten

Nach Konfigurationsänderungen (auf dem Pi via SSH):

docker restart homeassistant

Oder in der Web-Oberfläche: Einstellungen → System → Neustart

Backup einrichten

Automatisches Backup in Home Assistant

1. Gehe zu Einstellungen → System → Backups
2. Erstelle ein manuelles Backup zum Testen
3. Für automatische Backups: Addon “Auto Backup” (in Teil 3)

Docker Volume Backup

Einfaches Backup auf dem Pi erstellen (via SSH):

# Backup-Archiv im Home-Verzeichnis erstellen
tar -czvf homeassistant-backup-$(date +%Y%m%d).tar.gz ~/docker/home-assistant/config

Oder nutze dein bestehendes Docker Backup System.

Update-Strategie

Updates werden auf dem Pi ausgeführt (via SSH):

cd ~/docker/home-assistant
docker compose pull
docker compose up -d

Wichtig: Nutze Watchtower NICHT für Home Assistant! Updates können Breaking Changes enthalten. Prüfe vorher die Release Notes.

Troubleshooting

Logs prüfen

Auf dem Pi via SSH:

# Container Logs (letzte 100 Zeilen)
docker logs homeassistant --tail 100

# Home Assistant Core Logs (letzte 50 Zeilen)
cat ~/docker/home-assistant/config/home-assistant.log | tail -50

Permission denied beim Bearbeiten von Config-Dateien

Problem: Nach dem ersten Start bekommst du Permission denied wenn du configuration.yaml oder andere Dateien im config/ Ordner bearbeiten willst.

Ursache: Der Home Assistant Container läuft als root (wegen privileged: true) und erstellt beim ersten Start die Dateien mit root:root Ownership.

Lösung - 3 Möglichkeiten:

Option 1: Über den Container bearbeiten (empfohlen für Anfänger)

# Datei im Container bearbeiten
docker exec -it homeassistant nano /config/configuration.yaml

# Speichern: Ctrl+O, Enter, Ctrl+X
# Danach Home Assistant neu starten
docker restart homeassistant

Option 2: Datei von außen in Container kopieren

# Lokal bearbeiten (z.B. mit VSCode)
nano ~/docker/home-assistant/config/configuration.yaml  # Permission denied!

# Stattdessen: Temporär als anderer Dateiname bearbeiten
nano ~/tmp/configuration.yaml

# In Container kopieren (überschreibt alte Datei)
docker cp ~/tmp/configuration.yaml homeassistant:/config/configuration.yaml

# Home Assistant neu starten
docker restart homeassistant

Option 3: Permissions dauerhaft anpassen (fortgeschritten)

# EINMALIG nach erstem Container-Start
sudo chown -R $(whoami):$(whoami) ~/docker/home-assistant/config/

# Ab jetzt kannst du Dateien normal bearbeiten
nano ~/docker/home-assistant/config/configuration.yaml

Welche Option wählen?

• 🥇 Option 1: Sicher, funktioniert immer, aber weniger komfortabel
• 🥈 Option 2: Gut für einzelne Änderungen, etwas umständlich
• 🥉 Option 3: Komfortabel, aber kann bei neuen Dateien Probleme machen

Nächste Schritte

Dein Home Assistant läuft jetzt! Im nächsten Artikel zeige ich dir, wie du deine Smart Home Geräte integrierst:

• Philips Hue - Lampen und Sensoren
• TP-Link TAPO - Kameras, Steckdosen, Licht
• Homematic IP - Thermostate und Fensterkontakte

Damit vereinst du alle deine Smart Home Systeme in einer Oberfläche.

VIP Support

Du wirst hier einen groben Überblick finden.
Allerdings biete ich dir auch noch etwas mehr Support an:

• Du benötigst persönlichen Support
• Du möchtest von Beginn an Unterstützung bei deinem Projekt
• Du möchtest ein hier vorgestelltes Plugin durch mich installieren und einrichten lassen
• Du würdest gerne ein von mir erstelltes Script etwas mehr an deine Bedürfnisse anpassen

Für diese Punkte und noch einiges mehr habe ich einen limitierten VIP-Tarif eingerichtet.

VIP-Patreon Tarif Discord kontaktieren

Falls der Tarif gerade nicht verfügbar ist, kontaktiere mich auf Discord!

Geschafft - und wie geht’s weiter?

Home Assistant auf dem Raspberry Pi mit Docker zu installieren ist überraschend einfach. Der große Vorteil gegenüber Home Assistant OS: Du kannst es problemlos neben deinen anderen Docker-Containern betreiben.

Die Container-Variante ist ideal, wenn du bereits:

• Traefik als Reverse Proxy nutzt
• Grafana/InfluxDB für Monitoring hast
• Andere Dienste auf dem Pi laufen

Im nächsten Teil der Serie verbinden wir dann deine Smart Home Geräte und erstellen erste Automatisierungen.

Die komplette Serie

1. Home Assistant Installation (dieser Artikel)
2. Integrationen: TAPO, Hue, Homematic IP
3. Dashboards und Automatisierungen
4. Fortgeschritten: Traefik, VLANs, UniFi

Du hast Fragen oder Probleme? Schreib mir in den Kommentaren oder komm auf meinen Discord-Kanal.