Wer ein gemischtes Smart-Home-Ökosystem betreibt – Tuya-Steckdosen hier, Ring-Türklingel dort, TP-Link-Switches und vielleicht noch eine IP-Kamera –, stößt mit der Apple-Home-App schnell an ihre Grenzen: Sie spricht nur mit HomeKit-zertifizierten Geräten. Homebridge schließt diese Lücke, indem es als Brücke zwischen beliebigen Smart-Home-Protokollen und Apples HomeKit fungiert. Das Projekt ist kein Nischenprodukt: 25.000+ GitHub-Stars, über 2.000 Community-Plugins und eine sehr aktive Entwicklergemeinde sprechen für sich. Als Docker-Container läuft Homebridge auf jedem Linux-Server, auf einem Raspberry Pi oder auf einem NAS – ohne externe Datenbank, ohne komplexes Setup, ganz plattformneutral per docker compose.

Voraussetzungen

Linux-Host (physischer Server, VM, Raspberry Pi, NAS mit Docker-Unterstützung) – x86_64, arm64 oder arm32v7. Docker Desktop für macOS oder Windows ist nicht geeignet, da es Host-Networking über eine VM-Schicht implementiert und mDNS das lokale Netz nicht erreicht.
Docker Engine mit Compose-Plugin (V2, nicht das veraltete docker-compose V1). Installation: Docker und Docker Compose auf Linux installieren.
Gleiches lokales Netz wie deine Apple-Geräte (kein VLAN-Routing zwischen Host und iPhone/iPad/Mac – mDNS überquert keine Router-Grenzen).
Apple-Gerät (iPhone, iPad oder Mac) mit der Home-App für das initiale Pairing.
ca. 256 MB RAM frei; CPU-Last ist minimal (Node.js-Prozess, Raspberry Pi 2 reicht aus).
curl auf dem Host für die Verifikationsschritte.

Eckdaten auf einen Blick

Eigenschaft	Wert
Docker-Image	`homebridge/homebridge:latest` (Docker Hub)
Architektur	amd64, arm64v8, arm32v7 – automatische Auswahl
Basis-OS	Ubuntu 24.04
Web-UI-Port	8581 (Config-UI-X)
Netzwerk-Modus	host (Pflicht für mDNS/HomeKit)
Externe Datenbank	keine – alles im Volume
Standard-Login	admin / admin (sofort ändern!)
Vorinstalliert	ffmpeg mit libfdk-aac (für Kamera-Plugins)

Schritt 1: Projektordner und .env-Datei anlegen

Lege zunächst ein dediziertes Verzeichnis für das Homebridge-Projekt an. Wähle einen Pfad mit ausreichenden Schreibrechten – /opt/homebridge ist für Server üblich, im Home-Verzeichnis funktioniert es genauso.

sudo mkdir -p /opt/homebridge
cd /opt/homebridge

Erstelle die .env-Datei mit der Zeitzone. Das ist der einzige sinnvolle Kandidat für eine Auslagerung, da er je nach Standort variiert:

# /opt/homebridge/.env
TZ=Europe/Berlin

Für Österreich verwendest du Europe/Vienna, für die Schweiz Europe/Zurich.

Verifizieren: Prüfe, ob das Verzeichnis und die Datei vorhanden sind:

ls -la /opt/homebridge/
# Erwartete Ausgabe:
# .env

Schritt 2: compose.yaml erstellen

Das Herzstück der Installation ist die compose.yaml. Beachte besonders den network_mode: host – ohne ihn findet die Home-App die Bridge nicht. Wer ports: statt Host-Networking verwendet, sieht Homebridge zwar im Browser, aber Apple-Geräte bleiben blind dafür.

# /opt/homebridge/compose.yaml
services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: always
    network_mode: host
    volumes:
      - ./homebridge:/homebridge
    environment:
      - TZ=${TZ}
      - ENABLE_AVAHI=1
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "1"
    healthcheck:
      test: ["CMD-SHELL", "curl --fail http://localhost:8581 || exit 1"]
      interval: 60s
      retries: 5
      start_period: 300s
      timeout: 2s

Einige Erläuterungen zu den Schlüsselentscheidungen:

network_mode: host – Der Container teilt den Netzwerk-Stack des Hosts direkt. Port 8581 ist dadurch ohne explizites Port-Mapping am Host erreichbar. Diese Einstellung ist keine Option, sondern eine Pflicht für HomeKit.
ENABLE_AVAHI=1 – Aktiviert den eingebauten Avahi-mDNS-Daemon im Container. Wenn auf deinem Host bereits ein avahi-daemon läuft, setze diesen Wert auf 0 und mounte zusätzlich den Host-Socket (siehe Troubleshooting).
start_period: 300s – Beim allerersten Start installiert Homebridge Abhängigkeiten, was mehrere Minuten dauern kann. Der Healthcheck wartet diese Zeit ab, bevor er den Container als „unhealthy" markiert.
./homebridge:/homebridge – Das gesamte Daten-Volume: config.json, Plugins, Pairing-State. Nie löschen, immer sichern.

Verifizieren: Prüfe die Syntax der compose.yaml:

docker compose config
# Erwartete Ausgabe: Vollständige, normalisierte YAML-Ausgabe ohne Fehlermeldung

Schritt 3: Container starten

Beim allerersten Start zieht Docker das Image und legt das Volume-Verzeichnis ./homebridge an. Dann startet Homebridge und richtet die Node.js-Umgebung ein – das kann beim ersten Mal 2–5 Minuten dauern:

cd /opt/homebridge
docker compose up -d

Verfolge den Start-Fortschritt in den Logs:

docker compose logs -f homebridge

Homebridge ist bereit, wenn du in den Logs eine Zeile wie diese siehst:

[Homebridge] Homebridge is running on port 51826.
[Homebridge UI] Homebridge UI is listening on :: port 8581

Verifizieren: Prüfe den Container-Status und den HTTP-Endpunkt:

docker compose ps
# NAME          IMAGE                         STATUS
# homebridge    homebridge/homebridge:latest  Up (healthy)

curl -I http://localhost:8581
# HTTP/1.1 200 OK

Wenn der Status noch Up (health: starting) zeigt, warte noch 1–2 Minuten – das ist normal beim Erststart.

Schritt 4: Web-UI öffnen und Passwort ändern

Öffne im Browser http://<server-ip>:8581. Du erreichst die Config-UI-X – die Web-Oberfläche für Plugin-Verwaltung, Logs und HomeKit-Pairing.

Melde dich mit den Standard-Zugangsdaten an:

Benutzername: admin
Passwort: admin

Wichtig: Ändere das Passwort sofort nach dem ersten Login. Gehe dazu auf das Benutzer-Icon oben rechts → „Benutzer-Einstellungen" → neues Passwort vergeben. Die Standard-Credentials sind öffentlich bekannt; jeder im lokalen Netz könnte sonst die Homebridge-Konfiguration ändern.

Verifizieren: Nach dem Passwort-Wechsel erneut einloggen und die Startseite prüfen – Homebridge sollte als „Running" gemeldet sein. Im Tab „Logs" sollten keine roten Fehlermeldungen erscheinen.

Schritt 5: HomeKit-Pairing mit der Apple-Home-App

Auf der Startseite der Web-UI siehst du einen QR-Code und einen 8-stelligen Pairing-Code. Öffne auf deinem iPhone, iPad oder Mac die Home-App und folge diesen Schritten:

Tippe oben rechts auf das +-Symbol → „Zubehör hinzufügen".
Wähle „Weitere Optionen" (nicht automatisch suchen lassen).
Scanne den QR-Code aus der Homebridge-Web-UI oder gib den 8-stelligen Code manuell ein.
Bestätige die Sicherheitswarnung (Homebridge ist kein zertifiziertes HomeKit-Zubehör – das ist erwartet).
Weise die Bridge einem Raum zu und tippe auf „Fertig".

Nach dem Pairing erscheint die Homebridge-Bridge in der Home-App. Noch sind keine Geräte sichtbar – die kommen über Plugins.

Verifizieren: In der Homebridge-Web-UI unter „Homebridge" → Status sollte jetzt ein grünes „Paired" erscheinen. In den Container-Logs erscheint eine entsprechende Zeile:

docker compose logs homebridge | grep -i paired
# [Homebridge] Paired with new client

Schritt 6: Plugins installieren und erste Geräte einbinden

Plugins sind der eigentliche Mehrwert von Homebridge. Über den Tab „Plugins" in der Web-UI suchst du nach deinem Gerätehersteller oder Protokoll und installierst das passende Plugin mit einem Klick.

Beispiele für populäre Plugins:

homebridge-tuya-platform – Tuya/Smart Life-Geräte
homebridge-ring – Ring-Türklingeln und -Kameras
homebridge-tplink-smarthome – TP-Link Kasa-Steckdosen und Schalter
homebridge-camera-ffmpeg – IP-Kameras (nutzt das vorinstallierte ffmpeg mit libfdk-aac)

Alternativ kannst du Plugins direkt über die Kommandozeile installieren:

docker exec homebridge npm install -g homebridge-tuya-platform

Nach der Plugin-Installation musst du Homebridge neu starten. Das geht entweder über die Web-UI (roter „Restart"-Button) oder per Terminal:

docker compose restart homebridge

Anschließend konfigurierst du das Plugin über den automatisch erscheinenden Konfigurationsdialog in der Web-UI oder direkt in der config.json (Menüpunkt „Homebridge Config Editor").

Verifizieren: Nach dem Neustart erscheinen neu eingebundene Geräte in der Home-App. Prüfe außerdem die Logs auf Plugin-spezifische Fehlermeldungen:

docker compose logs homebridge | tail -50
# Keine roten ERROR-Zeilen zu Plugin-Initialisierung oder Gerätekonnektivität

Schritt 7: Updates und Backups

Homebridge bringt alle Abhängigkeiten (Node.js, npm, ffmpeg) im Image mit. Ein Update aktualisiert Image, Homebridge-Core, Config-UI-X und Node.js in einem Schritt:

cd /opt/homebridge
docker compose pull
docker compose up -d

Die Konfiguration und alle installierten Plugins bleiben dabei erhalten, da sie im Volume liegen. Plugin-Updates erfolgen separat über den Tab „Plugins" in der Web-UI.

Hinweis zu automatischen Updates: Watchtower ist für Homebridge offiziell nicht empfohlen (Stand 2025/2026). Automatische Image-Updates können zu Inkompatibilitäten mit installierten Plugins führen. Alternativen findest du in der Anleitung Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich.

Das Backup des gesamten homebridge/-Verzeichnisses ist besonders wichtig, da darin das Unterverzeichnis .persist/ liegt, das den HomeKit-Pairing-State enthält. Verlust dieses Verzeichnisses erzwingt ein vollständiges Re-Pairing aller Geräte in der Home-App. Sichere das Volume regelmäßig, z. B. nach der 3-2-1-Backup-Strategie:

# Einfaches Backup des gesamten homebridge-Verzeichnisses:
tar czf /backup/homebridge-$(date +%Y%m%d).tar.gz /opt/homebridge/homebridge/

Verifizieren: Nach einem Update prüfen, ob der Container wieder läuft und die Web-UI erreichbar ist:

docker compose ps
# Up (healthy)
curl -I http://localhost:8581
# HTTP/1.1 200 OK

Troubleshooting / Typische Fehler

Home-App zeigt „Kein Zubehör gefunden" oder Bridge nicht auffindbar: Fast immer fehlt network_mode: host. Ein ports:-Abschnitt statt Host-Networking ist die häufigste Ursache. Fix: network_mode: host setzen, ports: entfernen, Container neu starten.
Docker Desktop (macOS/Windows) – Bridge läuft, aber unsichtbar: Docker Desktop nutzt eine VM-Schicht; mDNS/Bonjour erreicht das physische Netz nicht. Homebridge läuft nur auf einem echten Linux-Host. Kein Workaround möglich.
Geräte erscheinen und verschwinden sporadisch (mDNS-Konflikt): Auf dem Host läuft bereits ein avahi-daemon und im Container ist ENABLE_AVAHI=1 gesetzt. Fix: ENABLE_AVAHI=0 setzen und folgende Volumes ergänzen: /var/run/dbus:/var/run/dbus und /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket.
Container bleibt „unhealthy" beim Erststart: Den start_period: 300s-Wert nicht verkleinern. Beim ersten Start installiert Homebridge Plugins und initialisiert die Node.js-Umgebung, was bis zu 5 Minuten dauern kann.
Bridge erreichbar, aber falsches Netzwerk-Interface für mDNS: Die HAP-Bibliothek wählt manchmal das docker0-Bridge-Interface statt des physischen Interfaces. Fix: In der Web-UI unter „Homebridge Settings" → „Network Interfaces" das korrekte physische Interface (z. B. eth0) manuell auswählen. Alternativ als mDNS-Advertiser „Avahi" oder „Ciao" wählen.
Plugin installiert, Geräte erscheinen nicht: Einige Plugins erfordern einen vollständigen Neustart (nicht nur Reload). Fix: docker compose restart homebridge oder Neustart über die Web-UI.
Home-App meldet „Bridge nicht erreichbar" nach Volume-Neuanlage: Das .persist/-Unterverzeichnis wurde gelöscht – der HomeKit-Pairing-State ist verloren. Fix: Re-Pairing durchführen. Künftig regelmäßig das gesamte homebridge/-Verzeichnis sichern.
mDNS testen auf dem Host: Mit avahi-browse -a -t auf dem Host prüfen – Homebridge sollte als _hap._tcp-Dienst auftauchen. Fehlt der Eintrag, liegt das Problem beim mDNS-Setup.

Häufige Fragen

Brauche ich eine Datenbank wie PostgreSQL oder MySQL?

Nein. Homebridge speichert die gesamte Konfiguration – config.json, Pairing-Daten und Plugins – in einem einzigen Volume-Verzeichnis. Du brauchst weder PostgreSQL noch Redis noch MySQL. Das macht das Setup deutlich einfacher und das Backup trivial: Das gesamte homebridge/-Verzeichnis sichern, fertig.

Wie paare ich Homebridge mit der Apple-Home-App?

Nach dem Start die Web-UI unter http://<server-ip>:8581 öffnen. Auf der Startseite siehst du einen QR-Code und einen 8-stelligen PIN. In der Apple-Home-App „Zubehör hinzufügen" → „Weitere Optionen" wählen und dann den QR-Code scannen oder den PIN manuell eingeben. Die Sicherheitswarnung bestätigen – sie erscheint, weil Homebridge kein offiziell zertifiziertes Zubehör ist.

Funktioniert Homebridge auf einem Raspberry Pi?

Ja, sehr gut sogar. Das offizielle Image unterstützt arm64v8 (Raspberry Pi 4/5 mit 64-Bit-OS) und arm32v7 (ältere Pis mit 32-Bit-OS). Das passende Architektur-Image wird beim docker pull automatisch gezogen – kein separates Image nötig. Raspberry Pi OS 64-Bit ist empfohlen.

Wie installiere ich neue Plugins?

Entweder über den Tab „Plugins" in der Web-UI (suchen, klicken, warten) oder per Terminal: docker exec homebridge npm install -g homebridge-<plugin-name>. Nach der Installation Homebridge neu starten und das Plugin in der Web-UI konfigurieren. Plugin-Updates erfolgen separat über den „Plugins"-Tab.

Kann ich mehrere HomeKit-Bridges mit Homebridge betreiben?

Ja. Seit Homebridge 1.x gibt es den Child-Bridge-Modus: Plugins können in eigenen Prozessen als separate HomeKit-Bridges laufen. Das isoliert Abstürze einzelner Plugins – stürzt ein Plugin ab, bleibt der Rest stabil. Die Konfiguration erfolgt pro Plugin über die Web-UI.

Was tue ich, wenn Geräte in der Home-App nicht erscheinen?

Systematisch vorgehen: Erstens sicherstellen, dass network_mode: host in der compose.yaml gesetzt ist. Zweitens docker compose logs homebridge auf Plugin-Fehlermeldungen prüfen. Drittens in den Homebridge-Einstellungen das korrekte physische Netzwerk-Interface auswählen. Viertens auf dem Host mit avahi-browse -a -t prüfen, ob der _hap._tcp-Dienst sichtbar ist.

Fazit

Homebridge ist die eleganteste Lösung für Apple-Nutzer mit heterogenem Smart-Home: Ein einzelner Docker-Container, kein Datenbank-Overhead, über 2.000 Plugins und eine ausgereifte Web-UI. Der einzige wirkliche Stolperstein ist network_mode: host – wer das verinnerlicht hat, hat in 15 Minuten eine laufende HomeKit-Bridge. Besonders auf einem Raspberry Pi oder einem kleinen Home-Server macht Homebridge eine sehr gute Figur. Wer ein noch breiteres Smart-Home-Fundament aufbauen möchte, dem sei ein Blick auf Home Assistant mit Docker empfohlen – die lokale Smart-Home-Zentrale, die sich hervorragend mit Homebridge kombinieren lässt. Für Zigbee-Geräte direkt im Docker-Stack bietet sich außerdem Phoscon/deCONZ in Docker als Ergänzung an.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: Homebridge Docker Wiki (GitHub) · Homebridge auf Docker Hub · Homebridge mDNS-Optionen