Home Assistant hinter Traefik im Docker-Container auf dem Raspberry Pi

Wer sein Smart Home auf ein solides, zukunftssicheres Fundament stellen möchte, landet früher oder später bei Home Assistant. Für viele beginnt die Reise mit dem fertigen Home Assistant OS (HAOS). Wenn man jedoch bereits eine modulare Docker-Infrastruktur betreibt, eigene Reverse-Proxy-Konzepte verfolgt und die volle Kontrolle über Netzwerk, Volumes und Updates behalten will, ist Home Assistant hinter Traefik im Docker-Container das Setup der Wahl.

In diesem Erfahrungsbericht nehme ich euch mit durch den Aufbau meiner Installation auf dem Raspberry Pi 5: Von der sauberen Container-Architektur über das Zusammenspiel mit Traefik v3.7 bis hin zu den typischen Tücken bei Reverse-Proxies, WebSocket-Verbindungen und SSH-Tuning.

Hardware-Basis: Lautlos, kühl und extrem schnell mit NVMe

Damit Home Assistant mit SQLite/Recorder-Datenbanken und Docker-Stacks langfristig stabil und ohne I/O-Engpässe läuft, scheidet eine microSD-Karte aus. Das Fundament bildet ein Raspberry Pi 5 mit nativer NVMe-SSD-Anbindung über PCIe und optimierter Aktivkühlung.

Teileliste & Komponenten

Komponente	Modell / Spezifikation	Funktion im Setup	Preis
SBC	Raspberry Pi 5 (8 GB RAM)*	Genug Headroom für Docker-Container, Home Assistant und Traefik.	189,99 €
PCIe M.2 HAT	Geekworm X1001 (M.2 NVMe SSD Shield)*	Unter dem Pi montiertes PCIe-Board, unterstützt Standard-2280-SSDs.	12,93 €
SSD	Fikwot FN501 Pro 256GB NVMe SSD – M.2 2280 PCIe Gen3 x4*	Maximale I/O-Performance und Haltbarkeit statt sterbender microSD-Karten.	51,99 €
Kühlung	Argon THRML 30mm Active Cooler (Black)*	Hochwertiger Vollaluminium-Kühlkörper mit PWM-Lüfter; hält SoC und PMIC dauerhaft kühl.	12,80 €
Gehäuse	Geekworm P579-V2*	Robustes Aluminium-Gehäuse mit optimalen Lüftungsschlitzen für den Argon THRML.	12,65 €
Stromversorgung	Offizielles Raspberry Pi 27W USB-C Netzteil*	Liefert stabile 5.1V / 5.0A für Pi, PCIe-Shield und NVMe-SSD.	16,07 €

In Summe hat mich die Hardware (im August 2026) somit 296,43 € gekostet.

Montage: Pi 5, Argon THRML, X1001 Shield & P579-V2

1. Argon THRML montieren: Die beiliegenden Wärmeleitpads passgenau auf CPU/SoC, RAM und PMIC des Raspberry Pi 5 anbringen. Den schwarzen Aluminium-Kühlkörper aufsetzen, über die gefederten Push-Pins fixieren und das 4-Pin-Kabel am FAN-Anschluss des Pi 5 einstecken.
2. X1001 Shield vorbereiten: Die M.2 NVMe SSD in den Slot der Geekworm X1001 Platine einsetzen und mit der Befestigungsschraube sichern.
3. PCIe-Flachbandkabel anschließen: Das FPC-Kabel vorsichtig am PCIe-Port des Pi 5 und der X1001-Platine arretieren.
4. Sandwich verschrauben: Pi 5 und X1001 Shield mit den beiliegenden Messing-Abstandshaltern zu einer stabilen Einheit verbinden.
5. Einbau ins P579-V2: Den Verbund in das P579-V2 Gehäuse einsetzen und verschrauben. Die Lüftungsschlitze der Oberschale sitzen exakt über dem 30mm-Lüfter des Argon THRML, während alle Ports an den Seiten bündig abschließen.

Installation & PCIe NVMe-Boot einrichten

Der eleganteste Weg ohne separaten USB-NVMe-Adapter führt über eine temporäre microSD-Karte: Das System wird initial auf der SD-Karte eingerichtet, bootet den Pi 5 mit dem montierten Geekworm X1001 Shield, klont sich selbst auf die NVMe und schaltet anschließend auf nativen PCIe Gen3-Boot um.

1. Temporäre microSD-Karte vorbereiten

• Stecke die microSD-Karte in deinen PC/Mac.
• Öffne den Raspberry Pi Imager und wähle Raspberry Pi OS Lite (64-bit) (Debian Bookworm).
• In den Einstellungen (Zahnrad-Symbol):
  • Hostname vergeben (z. B. home)
  • Benutzername & Passwort festlegen
  • SSH aktivieren (Passwort- oder Public-Key-Authentifizierung)
  • Zeitzone & Tastaturlayout konfigurieren
• Image auf die microSD-Karte schreiben.

2. Initialer Boot & System auf die NVMe kopieren

• microSD-Karte in den Pi 5 einstecken, Netzteil anschließen und per SSH verbinden.
• Prüfen, ob das Geekworm X1001 Shield und die NVMe-SSD erkannt werden:

lsblk

(Hier sollte neben mmcblk0 auch nvme0n1 gelistet sein).

• Das laufende System von der microSD-Karte direkt auf die NVMe-SSD kopieren (z. B. via rpi-clone oder dd):

# Schnelles Klonen des laufenden Systems auf die NVMe-SSD
sudo dd if=/dev/mmcblk0 of=/dev/nvme0n1 bs=4M status=progress conv=fsync

3. Bootloader-Reihenfolge auf NVMe umstellen

Damit der Pi 5 künftig standardmäßig von der NVMe-SSD startet:

sudo raspi-config

• Navigiere zu: Advanced Options → Bootloader Version → Latest (aktualisiert den Bootloader).
• Navigiere zu: Advanced Options → Boot Order → NVMe/USB Boot.
• raspi-config beenden, aber noch nicht neu starten.

4. PCIe Gen3 aktivieren & finaler Reboot

Um die volle Bandbreite der NVMe-SSD über das Geekworm X1001 Shield freizuschalten, aktiviere PCIe Gen3 in der Firmware-Konfiguration:

sudo nano /boot/firmware/config.txt

Füge am Ende der Datei folgende Zeilen ein:

# PCIe & Gen3 Geschwindigkeit für Geekworm X1001 aktivieren
dtparam=pciex1
dtparam=pciex1_gen=3

(Mit Strg + O, Enter speichern und mit Strg + X schließen).

Fahre das System herunter:

sudo poweroff

Entferne die microSD-Karte und schließe das Netzteil wieder an. Der Raspberry Pi 5 bootet nun in wenigen Sekunden geräuschlos direkt von der NVMe-SSD – gekühlt vom Argon THRML und bereit für Docker, Traefik und Home Assistant.

Das Architektur-Konzept: Home Assistant hinter Traefik im Docker-Container

Ziel des Setups:

• Modularität: Traefik und Home Assistant laufen in getrennten Compose-Stacks unter /opt/containers/.
• Sicherheit & Isolation: Home Assistant lauscht nicht direkt unverschlüsselt im LAN, sondern kommuniziert isoliert über ein dediziertes Docker-Bridge-Netzwerk (proxy-net) mit Traefik.
• TLS-Termination: Traefik fungiert als Ingress-Punkt, erzwingt HTTPS für den internen FQDN home.purrucker.deund leitet unverschlüsselten HTTP-Traffic (Port 80) direkt auf Port 443 um.
• Wartbarkeit: Strikte Versionsbindung (traefik:v3.7) schützt vor überraschenden Breaking Changes bei Major-Upgrades, während Minor- und Patch-Updates weiterhin sauber greifen.

Der Traefik v3 Stack

Im Traefik-Verzeichnis (/opt/containers/traefik/docker-compose.yml) setzen wir auf eine schlanke Konfiguration ohne externen ACME-/Let’s-Encrypt-Overhead, da die Domain rein intern im LAN aufgelöst wird und Traefik zur Laufzeit ein gültiges Default-Zertifikat bereitstellt.

services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - proxy-net
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      
      # EntryPoint HTTP -> Zwangsumleitung auf HTTPS
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      
      # EntryPoint HTTPS & Forwarded Headers
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.forwardedHeaders.insecure=true"

networks:
  proxy-net:
    external: true

Der Home Assistant Stack

Unter /opt/containers/homeassistant/docker-compose.yml wird Home Assistant an das proxy-net gehängt und über Traefik-Labels für den internen FQDN deklariert:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    privileged: true
    volumes:
      - /opt/containers/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    networks:
      - proxy-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ha.rule=Host(`DeinServer.DeineDomain.de`)"
      - "traefik.http.routers.ha.entrypoints=websecure"
      - "traefik.http.routers.ha.tls=true"
      - "traefik.http.services.ha.loadbalancer.server.port=8123"
      - "traefik.http.services.ha.loadbalancer.passhostheader=true"

networks:
  proxy-net:
    external: true

Stolpersteine aus der Praxis & Fehleranalyse

In der Theorie klingt das Setup simpel – in der Praxis traten während der Einrichtung jedoch einige spannende Hürden auf, die tiefen Einblick in die Architektur von Home Assistant und Docker geben.

Stolperstein 1: Der gefürchtete „400: Bad Request“

Nach dem ersten Aufruf von [https://DeinServer.DeineDomain.de](https://DeinServer.DeineDomain.de) quittierte Home Assistant den Dienst mit einem simplen 400: Bad Request.

Ein Blick in die Logs (docker logs homeassistant) verriet den Grund:

ERROR (MainThread) [homeassistant.components.http.forwarded] A request from a reverse proxy was received from 172.18.0.3, but your HTTP integration is not set-up for reverse proxies

Home Assistant verlangt aus Sicherheitsgründen eine explizite Freigabe, wenn Anfragen über einen Reverse-Proxy eintreffen. Hierbei half die präzise Analyse des Docker-Subnetzes:

docker network inspect proxy-net --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
# Ausgabe: 172.18.0.0/16

Stolperstein 2: Storage-Cache & Migration in die UI

Obwohl die configuration.yaml sauber gepflegt war, persistierte der Fehler zunächst. Der Grund: Home Assistant nutzt einen internen Konfigurationsspeicher (.storage), der beim Booten den HTTP-Zustand cacht (Using stable HTTP config), bevor nachgelagerte YAML-Dateien vollständig ausgewertet sind.

Die Lösung:

1. Cache bereinigen:

Den temporär gespeicherten HTTP- und Config-State im .storage-Verzeichnis entfernen:

sudo rm -f /opt/containers/homeassistant/config/.storage/http
sudo rm -f /opt/containers/homeassistant/config/.storage/core.config_entries

2. Sauberer Recreate:

Den Container neu aufbauen, damit die YAML-Werte initial importiert werden:

cd /opt/containers/homeassistant
docker compose down && docker compose up -d

3. UI-Migration abschließen:

Nach dem ersten Start meldet Home Assistant eine Reparatur-Warnung, dass die HTTP-Konfiguration künftig über das Frontend gepflegt wird. Unter Einstellungen → System → Netzwerk die vertrauenswürdigen Proxys (172.18.0.0/16, 172.16.0.0/12) hinterlegen und den http:-Block anschließend vollständig aus der configuration.yaml entfernen.

Stolperstein 3: „Unable to connect“ – Der WebSocket-Hänger

Nach erfolgreichem Login erschien plötzlich die Meldung „Unable to connect to Home Assistant – Retrying…“.

Während der initiale Login über klassisches HTTPS läuft, schaltet das Home Assistant Frontend für Dashboard und Entitäts-Updates sofort auf WebSockets (/api/websocket) um. Fehlen hier die passenden Forwarded-Header oder der Host-Header, schlägt der Handshake fehl.

Die Lösung:

1. PassHostHeader in Home Assistant aktivieren:

In der /opt/containers/homeassistant/docker-compose.yml sicherstellen, dass Traefik den ursprünglichen Hostnamen durchreicht:

labels:
  - "traefik.http.services.ha.loadbalancer.passhostheader=true"

2. Forwarded Headers im Traefik Entrypoint erlauben:

In der /opt/containers/traefik/docker-compose.yml Traefik anweisen, die Proxy-Header des Entrypoints zu akzeptieren:

command:
  - "--entrypoints.websecure.forwardedHeaders.insecure=true"

5. Stacks neu starten & Browser-Cache leeren:

Traefik und Home Assistant neu starten und das Dashboard mit Shift + F5 (Mac: Cmd + Shift + R) laden – der WebSocket verbindet sich sofort stabil.

Feinschliff: SSH-Hänger und Wi-Fi Power Management

Wer den Raspberry Pi per SSH administriert, kennt möglicherweise das Phänomen: Tippt man nach wenigen Minuten Pause wieder im Terminal, friert die Eingabe für 2–4 Sekunden ein, bevor die Zeichen erscheinen.

Verantwortlich dafür sind meist aggressive Energiesparmodi des WLAN-Chipsatzes (Power Management). Um das dauerhaft zu unterbinden, lässt sich das Power Saving über den NetworkManager global abschalten:

# /etc/NetworkManager/conf.d/default-wifi-powersave-on.conf
[connection]
wifi.powersave = 2

In Kombination mit einem Keep-Alive in der lokalen Client-Konfiguration (~/.ssh/config):

Host *
    ServerAliveInterval 30
    ServerAliveCountMax 3

bleibt die SSH-Verbindung auch nach längeren Denkpausen sofort reaktiv.

Fazit

Die Kombination aus Home Assistant Core im Docker-Container und Traefik v3.7 als Reverse-Proxy bietet die perfekte Balance aus Sicherheit, Performance und Flexibilität. Durch die strikte Trennung von Ingress-Routing und Anwendungslogik bleibt das Host-System übersichtlich, Backups der Compose-Verzeichnisse genügen für einen schnellen Restore, und das Smart Home ist sauber über HTTPS im Heimnetz erreichbar.