Homebridge mit Docker installieren

Wenn bei dir zu Hause bereits ein Linux-Homeserver, ein NAS von Synology oder QNAP oder ein Unraid-Server durchläuft, kannst du Homebridge direkt als Docker-Container starten. Du brauchst keine extra Hardware kaufen, belegst keine weitere Steckdose und Homebridge läuft sauber getrennt vom restlichen System. Nach einem Server-Neustart fährt der Container automatisch wieder hoch.

Diese Anleitung führt dich durch die technischen Voraussetzungen wie das Host-Netzwerk, zeigt die Einrichtung mit Docker Compose oder Portainer und erklärt die Steuerung über die Homemanager App oder den Browser.

Warum Homebridge in Docker?

• Keine zusätzliche Hardware: Du nutzt bestehende Reserven deines Servers und sparst dir Anschaffungskosten sowie zusätzlichen Stromverbrauch.
• Saubere Kapselung: Node.js, Bibliotheken und Homebridge bleiben im Container. Dein Basis-Betriebssystem wird nicht mit globalen Paketen verändert.
• Einfache Backups und Umzüge: Deine Einstellungen, Plugins und HomeKit-Pairings liegen in einem einzigen Ordner auf deinem Host. Ein Serverwechsel ist damit schnell erledigt.
• Automatischer Neustart: Über die Restart-Policy (restart: unless-stopped) startet Docker Homebridge nach Abstürzen oder Server-Reboots selbstständig wieder.
• FFmpeg bereits an Bord: Das offizielle Image bringt ffmpeg mit Audio-Unterstützung ab Werk mit, sodass viele Video- und Kamera-Plugins sofort einsatzbereit sind.

Einschränkung: Docker Desktop unter macOS und Windows

Wichtige Voraussetzungen für den Container-Betrieb

Damit Apple Home deine Geräte erkennt und Daten dauerhaft gespeichert bleiben, sind zwei Einstellungen im Container entscheidend. Die nachfolgenden Konfigurationen und Vorlagen berücksichtigen beide Punkte bereits ab Werk:

1. Host-Netzwerkmodus (network_mode: host)

Docker sperrt Container standardmäßig in ein eigenes, isoliertes Bridge-Netzwerk. Apple HomeKit nutzt zur Erkennung im Netzwerk jedoch mDNS (Bonjour über UDP-Port 5353). Diese Multicast-Pakete können ein Standard-Docker-Netzwerk nicht verlassen.

Homebridge muss deshalb im Host-Netzwerkmodus (network_mode: host bzw. --net=host) betrieben werden. Der Container nutzt dadurch direkt die IP-Adresse und Netzwerkkarte deines Host-Systems.

2. Dauerhafter Speicher (/homebridge)

Container verwerfen interne Änderungen beim Löschen oder Aktualisieren des Images.

Das interne Verzeichnis /homebridge muss deshalb auf einen Ordner deines Servers gemountet werden. Dort legt Homebridge die config.json, installierte Plugins, Cache-Dateien und die Pairing-Schlüssel für Apple Home ab.

Installation & Bereitstellung

Das offizielle Image wird vom Homebridge-Projekt gepflegt (homebridge/homebridge:latest) und unterstützt Intel/AMD-Prozessoren (amd64) sowie ARM-Systeme (arm64, armv7).

mkdir -p ~/homebridge
cd ~/homebridge

services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/homebridge
    environment:
      - TZ=Europe/Berlin
      - PUID=1000
      - PGID=1000
      - HOMEBRIDGE_CONFIG_UI_PORT=8581

docker compose up -d

mkdir -p ~/homebridge/data

docker run -d \
  --name=homebridge \
  --restart=unless-stopped \
  --net=host \
  -v ~/homebridge/data:/homebridge \
  -e TZ=Europe/Berlin \
  -e PUID=1000 \
  -e PGID=1000 \
  -e HOMEBRIDGE_CONFIG_UI_PORT=8581 \
  homebridge/homebridge:latest

Konfiguration auf NAS- und Server-Systemen

Verbindung herstellen und einrichten

Sobald der Container läuft, ist Homebridge im Heimnetzwerk erreichbar. Die Weboberfläche (homebridge-config-ui-x) dient als Browser-Dashboard und stellt die API bereit, über die sich auch Homemanager verbindet.

Die Instanz läuft standardmäßig unverschlüsselt über Port 8581.

Da noch kein Benutzer existiert, legst du beim ersten Verbinden ein Administratorkonto an. Das geht in der App oder im Browser:

http://<deine-server-ip>:8581

Wartung & praktische Befehle

Im laufenden Betrieb gibt es bei Docker zwei Ebenen für Updates:

1. Plugins und Homebridge Core aktualisieren

Plugins sowie Aktualisierungen für Homebridge Core spielst du direkt in der Homemanager App oder über das Webinterface ein. Alle Daten liegen im gemounteten Ordner /homebridge. Deine Einstellungen und Updates bleiben erhalten, wenn der Container neu startet. Ein Neuerstellen des Containers ist dafür nicht nötig.

2. Das Docker-Image aktualisieren (Node.js & OS)

Um Sicherheits-Updates des Containers und neuere Node.js LTS-Versionen einzuspielen, aktualisierst du gelegentlich das Basis-Image:

# In den Ordner mit der docker-compose.yml wechseln:
cd ~/homebridge

# Neueste Version herunterladen
docker compose pull

# Container neu starten (deine Daten bleiben erhalten)
docker compose up -d

3. Nützliche Befehle: Terminal, App & Web-UI

Du musst für Wartungsarbeiten nicht zwingend eine SSH-Verbindung auf dem Host öffnen. Viele Befehle kannst du auf unterschiedlichen Wegen ausführen:

• In der Homemanager App & Weboberfläche: Beide Oberflächen bieten ein integriertes Terminal, mit dem du Befehle direkt in der Umgebung des Servers absetzen kannst.
• Per Host-Terminal (docker exec): Wenn du ohnehin per SSH auf deinem Linux-Server arbeitest, führst du Befehle mit docker exec im laufenden Container aus.

# Admin-Passwort zurücksetzen (setzt den Login auf admin/admin zurück)
docker exec -it homebridge hb-service reset-admin

# Live-Logs ansehen
docker logs -f homebridge

# Interaktive Konsole im Container aufrufen
docker exec -it homebridge sh

# Container neu starten
docker restart homebridge

4. Zusätzliche Systempakete installieren (PACKAGES)

Manche Plugins benötigen zusätzliche Linux-Programme (wie Bluetooth-Tools oder native Treiber).

Das offizielle Image kann diese Pakete beim Containerstart automatisch nachinstallieren. Trage die benötigten Pakete dazu in der docker-compose.yml unter environment ein:

environment:
  - TZ=Europe/Berlin
  - PACKAGES=libcap2-bin,iputils-ping

Häufige Probleme schnell lösen

Nächste Schritte

Sobald deine Homebridge im Container läuft, richtest du deine Geräte ein:

1. Mit Apple Home koppeln:
   Scanne den QR-Code aus dem Dashboard oder der Homemanager App mit der Apple-Home-App auf deinem iPhone.
   Schritt-für-Schritt-Anleitung zur Apple Home Kopplung

2. Plugins installieren:
   Suche in Homemanager oder über die Weboberfläche nach Erweiterungen für deine Geräte (z. B. Tuya, Shelly, FritzBox, Ring oder Kameras).
   Tipps zur Auswahl und Bewertung von Plugins

3. Child Bridges einrichten:
   Teile Plugins in eigenständige Teilprozesse auf. Wenn ein einzelnes Plugin Schluckauf hat, läuft der Rest deines Smart Homes ungestört weiter.
   Mehr über Child Bridges erfahren

Weiterführende Links

• Offizielles Homebridge Wiki: Install Homebridge on Docker
• Offizielles Docker Image Repository (homebridge/homebridge)
• Homebridge Docker Image auf Docker Hub
• Homebridge auf Unraid (Wiki)
• Homebridge auf QNAP Container Station (Wiki)
• Homebridge auf TrueNAS SCALE (Wiki)
• Offizieller Homebridge Discord Server (#docker Channel)
• Docker Dokumentation: Host-Netzwerk-Treiber