# Homebridge mit Docker installieren (https://docs.homemanager-app.de/de/guide/install-docker) 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? [#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 [#einschränkung-docker-desktop-unter-macos-und-windows] **mDNS-Problem bei Docker Desktop (macOS & Windows):**\ Docker Desktop lässt Container auf macOS und Windows in einer virtuellen Linux-Maschine laufen. Diese Virtualisierung verhindert, dass der Host-Netzwerkmodus (`network_mode: host`) Multicast- und mDNS-Signale (Bonjour über UDP-Port 5353) an dein eigentliches Heimnetz durchreicht. Apple Home kann die Bridge deshalb nicht finden und meldet dauerhaft *„Keine Antwort“* (dokumentiert im [Docker-Desktop-Issue #570](https://github.com/homebridge/docker-homebridge/issues/570)). Verwende Docker für Homebridge daher auf **Linux** (Debian, Ubuntu, Raspberry Pi OS), auf einem **NAS** (Synology, QNAP) oder unter **Unraid / Proxmox**. Für macOS empfehlen wir die [native macOS-Installation](/de/guide/install-macos), für Windows die [Windows-Dienst-Installation](/de/guide/install-windows). *** ## Wichtige Voraussetzungen für den Container-Betrieb [#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`) [#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`) [#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 [#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`). **Hinweis zum Image-Namen:** Das Image wurde früher unter `oznu/homebridge` geführt. Verwende für Neuinstallationen und Updates die offizielle Repository-Adresse **`homebridge/homebridge`** auf [Docker Hub](https://hub.docker.com/r/homebridge/homebridge). ### Methode 1: Einrichtung mit Docker Compose [#methode-1-einrichtung-mit-docker-compose] [Docker Compose](https://docs.docker.com/compose/) ist der übersichtlichste Weg, um Container aufzubauen und langfristig zu pflegen. #### Projektordner anlegen [#projektordner-anlegen] Erstelle auf deinem Host einen Ordner für Homebridge und wechsle hinein: ```bash mkdir -p ~/homebridge cd ~/homebridge ``` #### `docker-compose.yml` erstellen [#docker-composeyml-erstellen] Lege die Konfigurationsdatei an (z. B. mit `nano docker-compose.yml`) und trage folgendes ein: ```yaml 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 ``` Die wichtigsten Parameter: * `network_mode: host`: Verbindet den Container direkt mit dem Host-Netzwerk (für HomeKit erforderlich). * `volumes`: Leitet den lokalen Ordner `./data` an den internen Pfad `/homebridge` weiter. * `TZ`: Setzt deine Zeitzone für korrekte Uhrzeiten in Automationsregeln und Protokollen. * `PUID` & `PGID`: Benutzer- und Gruppen-ID deines Linux-Users (im Terminal mit dem Befehl `id` abrufbar). Verhindert Schreibprobleme im gemounteten Ordner. * `HOMEBRIDGE_CONFIG_UI_PORT`: Web-Port für das Dashboard und die Homemanager-API (Standard: 8581). #### Container starten [#container-starten] Starte den Dienst im Hintergrund: ```bash docker compose up -d ``` Docker lädt das Image herunter und startet Homebridge. Nach wenigen Augenblicken ist der Server im Netzwerk aktiv. ### Methode 2: Schnellstart mit `docker run` [#methode-2-schnellstart-mit-docker-run] Falls du ohne Compose-Datei arbeiten möchtest, kannst du den Container mit einem Aufruf über das [Docker CLI](https://docs.docker.com/engine/reference/commandline/run/) starten: ```bash 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 ``` ### Methode 3: Portainer Stack [#methode-3-portainer-stack] Verwendest du zur Container-Verwaltung die Weboberfläche [Portainer](https://www.portainer.io/): 1. Öffne Portainer im Browser und wähle deine Umgebung (*Local*) aus. 2. Klicke in der Seitenleiste auf **Stacks** und dann auf **Add stack**. 3. Gib als Namen `homebridge` ein. 4. Wähle als Methode den **Web editor** und füge die Compose-Definition ein: ```yaml version: '3.8' services: homebridge: image: homebridge/homebridge:latest container_name: homebridge restart: unless-stopped network_mode: host volumes: - /var/lib/homebridge:/homebridge environment: - TZ=Europe/Berlin - PUID=1000 - PGID=1000 - HOMEBRIDGE_CONFIG_UI_PORT=8581 ``` *(Passe `/var/lib/homebridge` an deinen gewünschten Speicherpfad auf dem Server an).* 5. Klicke unten auf **Deploy the stack**. *** ## Konfiguration auf NAS- und Server-Systemen [#konfiguration-auf-nas--und-server-systemen] Synology-Modelle der Plus-Serie (Intel oder AMD, wie DS224+, DS720+, DS920+, DS1522+) unterstützen im DSM 7.2 **Container Manager** direkt Docker Compose Stacks. Wenn du eine DiskStation der j- oder Play-Serie (z. B. DS220j, DS120j) ohne Docker besitzt oder lieber eine native App ohne Container nutzt, greife zum offiziellen SPK-Paket. Eine komplette Anleitung dazu findest du in unserem [Synology NAS Leitfaden](/de/guide/install-synology). 1. Öffne die **File Station** und erstelle im Ordner `docker` einen neuen Unterordner `homebridge`. 2. Öffne den **Container Manager** und gehe links auf **Projekt**. 3. Klicke auf **Erstellen**: * **Projektname:** `homebridge` * **Pfad:** Wähle `/docker/homebridge` aus. * **Quelle:** Wähle *docker-compose.yaml erstellen* und füge die Konfiguration ein: ```yaml services: homebridge: image: homebridge/homebridge:latest container_name: homebridge restart: unless-stopped network_mode: host volumes: - /volume1/docker/homebridge:/homebridge environment: - TZ=Europe/Berlin - HOMEBRIDGE_CONFIG_UI_PORT=8581 ``` 4. Klicke auf **Weiter** und beende die Einrichtung. DSM lädt das Image und startet den Container. Unter Unraid richtest du Homebridge bequem über die [Community Applications](https://unraid.net/community/apps) ein (siehe auch die [offizielle Unraid-Dokumentation von Homebridge](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-Unraid)): 1. Öffne im Unraid-Webinterface den Reiter **Apps**. 2. Suche nach `Homebridge` und wähle die Vorlage des offiziellen Images aus. 3. Kontrolliere die Einstellungen: * **Network Type:** Muss auf **Host** stehen (für mDNS). * **AppData Storage:** Üblicherweise `/mnt/user/appdata/homebridge`, gemountet auf `/homebridge`. 4. Klicke auf **Apply**. Unter QTS oder QuTS hero nutzt du die [QNAP Container Station](https://www.qnap.com/de-de/software/container-station) (siehe die [offizielle QNAP-Anleitung im Wiki](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-QNAP)): 1. Öffne die **Container Station** und wechsle zu **Anwendungen** (bzw. *Erstellen*). 2. Lege eine neue Anwendung namens `homebridge` an. 3. Trage die YAML-Compose-Konfiguration ein und achte auf `network_mode: host`. 4. Mappe als Volume einen Pfad auf deinem Speicherpool (z. B. `/share/Container/homebridge:/homebridge`). 5. Klicke auf **Erstellen** und starte den Dienst. * **Proxmox VE:** Für minimale Systemlast kannst du einen schlanken LXC-Container (Debian oder Alpine) aufsetzen und Docker darin betreiben. Achte darauf, dass der LXC mit Nesting konfiguriert ist oder bei Bedarf als privilegierter Container vollen Netzzugriff hat. * **TrueNAS SCALE:** Nutze den App-Katalog oder richte eine benutzerdefinierte Compose-App mit Host-Netzwerkmodus und persistentem Dataset für `/homebridge` ein (Details im [TrueNAS Scale Wiki](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-TrueNAS-Scale)). *** ## Verbindung herstellen und einrichten [#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: ### Einrichtung mit Homemanager [#einrichtung-mit-homemanager] Mit Homemanager verwaltest du Instanzen auf dem iPhone oder iPad, liest Logs in Echtzeit und konfigurierst Plugins. #### Suchlauf starten [#suchlauf-starten] Öffne Homemanager im selben WLAN wie der Host-Server. Tippe im Startdialog auf **Mit Server verbinden** (oder in den Einstellungen auf **Plattform hinzufügen**). Durch das Host-Netzwerk findet die App die Instanz automatisch per mDNS/Bonjour. #### Server wählen [#server-wählen] Wähle die gefundene Instanz aus der Liste. Sie erscheint mit dem Homebridge-Symbol und Port `8581`. #### Benutzer anlegen [#benutzer-anlegen] Homemanager erkennt die neue Instanz und öffnet die Maske **Neuen Benutzer erstellen**. Trage Anzeigenamen, Benutzernamen (z. B. `admin`) und Passwort ein und tippe auf **Erstellen und anmelden**. Das Konto wird auf dem Server eingerichtet und die Zugangsdaten im iOS-Schlüsselbund hinterlegt. Homemanager verbindet sich anschließend automatisch. Klappt der Suchlauf nicht oder läuft Docker auf einem Remote-Server? Der Guide [Server mit Homemanager verbinden](/de/guide/connecting-servers) beschreibt die manuelle Verbindung per IP und Port sowie typische Netzwerkprobleme. ### Einrichtung im Webbrowser [#einrichtung-im-webbrowser] Für die Konfiguration am Computer rufst du die Weboberfläche direkt im Browser auf. #### Adresse aufrufen [#adresse-aufrufen] Öffne einen Browser und rufe die Weboberfläche auf: ``` http://:8581 ``` *(Beispiel: `http://192.168.178.50:8581` oder `http://homebridge.local:8581`).* #### Konto einrichten oder Backup einspielen [#konto-einrichten-oder-backup-einspielen] Gib einen Benutzernamen und ein Passwort für das Administratorkonto ein. Wenn du von einem früheren Server wechselst, kannst du an dieser Stelle stattdessen ein bestehendes Backup wiederherstellen. Nach der Anmeldung zeigt die Weboberfläche das Dashboard mit dem HomeKit-QR-Code. *** ## Wartung & praktische Befehle [#wartung--praktische-befehle] Im laufenden Betrieb gibt es bei Docker zwei Ebenen für Updates: ### 1. Plugins und Homebridge Core aktualisieren [#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) [#2-das-docker-image-aktualisieren-nodejs--os] Um Sicherheits-Updates des Containers und neuere Node.js LTS-Versionen einzuspielen, aktualisierst du gelegentlich das Basis-Image: ```bash # 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 [#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. ```bash # 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 ``` Wenn du das Webinterface oder die Homemanager App bereits geöffnet hast, kannst du `hb-service`-Befehle auch bequem im dortigen Terminal-Fenster eingeben, ohne das Host-Präfix `docker exec -it homebridge`. ### 4. Zusätzliche Systempakete installieren (`PACKAGES`) [#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: ```yaml environment: - TZ=Europe/Berlin - PACKAGES=libcap2-bin,iputils-ping ``` *** ## Häufige Probleme schnell lösen [#häufige-probleme-schnell-lösen] Bei Docker liegt die Ursache fast immer an der mDNS-Übertragung im Netzwerk: * **Host-Netzwerk prüfen:** Kontrolliere, ob der Container wirklich mit `network_mode: host` läuft. In normalen Docker-Bridge-Netzwerken werden mDNS-Signale geblockt. * **Avahi-Dienst auf dem Host:** Läuft auf deinem Linux-Server bereits der Dienst `avahi-daemon`, kann es zu Konflikten auf Port 5353 kommen. Stelle in den Homebridge-Einstellungen unter *Erweiterte Einstellungen* den mDNS-Advertiser von *Bonjour HAP* auf **Ciao** um. Alternativ kannst du im Container `ENABLE_AVAHI=0` setzen und die Host-Sockets mounten: ```yaml volumes: - ./data:/homebridge - /var/run/dbus:/var/run/dbus - /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket environment: - ENABLE_AVAHI=0 ``` * **WLAN-Gastnetzwerk:** Dein iPhone oder iPad und der Server müssen im regulären Heimnetz sein. Gastnetze trennen Geräte voneinander, sodass die Erkennung fehlschlägt. Im Host-Netzwerkmodus teilt sich Homebridge alle Ports mit deinem Server. Wenn ein anderer Dienst bereits Port 8581 belegt, kann Homebridge das Dashboard nicht starten. Du kannst den Port in deiner `docker-compose.yml` anpassen: ```yaml environment: - HOMEBRIDGE_CONFIG_UI_PORT=8585 ``` Anschließend erreichst du die Oberfläche unter `http://:8585`. Erscheint im Protokoll der Fehler `EACCES: permission denied`, fehlen dem Container die Schreibrechte für den gemounteten Ordner auf deinem Host. 1. Prüfe deine Benutzer- und Gruppen-ID im Terminal: ```bash id ``` 2. Trage die angezeigten Zahlen bei `PUID` und `PGID` in der Compose-Datei ein. 3. Korrigiere die Berechtigungen deines Datenordners auf dem Host: ```bash sudo chown -R 1000:1000 ~/homebridge/data ``` Falls du dein Passwort verlegt hast, kannst du es über das Terminal deines Hosts zurücksetzen: ```bash docker exec -it homebridge hb-service reset-admin ``` Der Befehl setzt Benutzername und Kennwort auf `admin` / `admin` zurück. Nach dem Anmelden kannst du sofort ein neues Kennwort festlegen. *** ## Nächste Schritte [#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](/de/guide/pairing-apple-home) 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](/de/guide/finding-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](/de/guide/child-bridges) *** ## Weiterführende Links [#weiterführende-links] * [Homebridge installieren: Alle Methoden](/de/guide/install-homebridge) * [Offizielles Homebridge Wiki: Install Homebridge on Docker](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker) * [Offizielles Docker Image Repository (homebridge/homebridge)](https://github.com/homebridge/docker-homebridge) * [Homebridge Docker Image auf Docker Hub](https://hub.docker.com/r/homebridge/homebridge) * [Homebridge auf Unraid (Wiki)](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-Unraid) * [Homebridge auf QNAP Container Station (Wiki)](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-QNAP) * [Homebridge auf TrueNAS SCALE (Wiki)](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-TrueNAS-Scale) * [Offizieller Homebridge Discord Server (#docker Channel)](https://discord.gg/Cmq8a44) * [Docker Dokumentation: Host-Netzwerk-Treiber](https://docs.docker.com/engine/network/drivers/host/)