Die Apple-Home-App spricht nur mit HomeKit-zertifizierten Geräten; Tuya-Steckdosen, Ring-Türklingel, TP-Link-Switches oder IP-Kameras bleiben außen vor. Homebridge schließt diese Lücke als Brücke zwischen beliebigen Smart-Home-Protokollen und HomeKit, mit über 25.000 GitHub-Stars und über 2.000 Community-Plugins. Als Docker-Container läuft Homebridge per docker compose auf jedem Linux-Server, Raspberry Pi oder NAS, ohne externe Datenbank.

Voraussetzungen

Linux-Host (Server, VM, Raspberry Pi, NAS mit Docker) – x86_64, arm64 oder arm32v7. Docker Desktop für macOS oder Windows ist nicht geeignet: Host-Networking läuft dort über eine VM-Schicht, mDNS erreicht das lokale Netz nicht.
Docker Engine mit Compose-Plugin (V2, nicht das veraltete docker-compose V1). Installation: Docker und Docker Compose auf Linux installieren.
Gleiches lokales Netz wie Ihre 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, ohne Kamera-Plugins; CPU-Last ist gering (Node.js-Prozess, ein Raspberry Pi 2 reicht aus). Rund 1,5 GB freier Speicher für Image und Plugins.
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
Erster Login	Einrichtungsassistent legt ein eigenes Admin-Konto an
Vorinstalliert	ffmpeg mit libfdk-aac (für Kamera-Plugins)

Schritt 1: Projektordner und .env-Datei anlegen

Legen Sie ein eigenes Projektverzeichnis mit Schreibrechten an; /opt/homebridge ist auf Servern üblich, das Home-Verzeichnis funktioniert genauso.

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

Erstellen Sie die .env-Datei mit der Zeitzone (z. B. sudo nano /opt/homebridge/.env), dem einzigen standortabhängigen Wert:

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

Für Österreich verwenden Sie Europe/Vienna, für die Schweiz Europe/Zurich.

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

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

Schritt 2: compose.yaml erstellen

Entscheidend in der compose.yaml ist network_mode: host: Mit ports: statt Host-Networking erreichen Sie Homebridge zwar im Browser, Apple-Geräte finden die Bridge aber nicht.

# /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; Port 8581 ist ohne Port-Mapping erreichbar. Für HomeKit Pflicht.
ENABLE_AVAHI=1 – Aktiviert den eingebauten Avahi-mDNS-Daemon im Container. Wenn auf Ihrem Host bereits ein avahi-daemon läuft, setzen Sie diesen Wert auf 0 und binden zusätzlich den Host-Socket ein (siehe Troubleshooting).
start_period: 300s – Beim ersten Start installiert Homebridge Abhängigkeiten, was mehrere Minuten dauern kann; so lange markiert der Healthcheck den Container nicht als „unhealthy“.
./homebridge:/homebridge – Das gesamte Daten-Volume: config.json, Plugins, Pairing-State. Nie löschen, immer sichern.

Verifizieren: Prüfen Sie die Syntax der compose.yaml:

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

Schritt 3: Container starten

Beim ersten Start zieht Docker das Image, legt ./homebridge an und Homebridge richtet die Node.js-Umgebung ein, was 2–5 Minuten dauern kann:

cd /opt/homebridge
docker compose up -d

Verfolgen Sie den Start-Fortschritt in den Logs:

docker compose logs -f homebridge

Homebridge ist bereit, wenn in den Logs Zeilen wie diese erscheinen (Versionen, Bridge-Name und Port weichen ab):

[Homebridge] Homebridge v2.4.0 (HAP v…) (Homebridge 1A2B) is running on port 51826.
[Homebridge UI] Homebridge UI v5.29.0 is listening on :: port 8581.

Verifizieren: Prüfen Sie 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

Zeigt der Status noch Up (health: starting), warten Sie 1 bis 2 Minuten.

Schritt 4: Web-UI öffnen und Admin-Konto anlegen

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

Beim ersten Aufruf startet ein Einrichtungsassistent. Es gibt kein voreingestelltes Standardkonto mehr:

Benutzernamen und ein sicheres Passwort für das Admin-Konto festlegen.
Alternativ an dieser Stelle ein vorhandenes Homebridge-Backup wiederherstellen.

Wichtig: Führen Sie den Assistenten sofort durch. Solange kein Konto existiert, kann jeder im lokalen Netz das Admin-Konto anlegen und die Konfiguration ändern.

Verifizieren: Abmelden und mit dem neuen Konto erneut anmelden. Die Startseite meldet Homebridge als laufend, und in den Logs erscheinen keine roten Fehlermeldungen.

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

Die Startseite der Web-UI zeigt einen QR-Code und einen 8-stelligen Pairing-Code. Öffnen Sie auf iPhone, iPad oder Mac die Home-App:

Oben rechts auf das +-Symbol tippen → „Zubehör hinzufügen“.
„Weitere Optionen“ wählen (nicht automatisch suchen lassen).
Den QR-Code aus der Homebridge-Web-UI scannen oder den 8-stelligen Code manuell eingeben.
Die Sicherheitswarnung bestätigen (Homebridge ist kein zertifiziertes HomeKit-Zubehör – das ist erwartet).
Die Bridge einem Raum zuweisen und auf „Fertig“ tippen.

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

Verifizieren: Das QR-Code-Widget auf der Startseite der Web-UI zeigt jetzt „Gekoppelt“ statt „Nicht gekoppelt“, und die Bridge erscheint in der Home-App unter dem zugewiesenen Raum.

Schritt 6: Plugins installieren und erste Geräte einbinden

Im Tab „Plugins“ der Web-UI suchen Sie nach Hersteller oder Protokoll und installieren 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 per Kommandozeile mit hb-service, das die Plugins ins persistente Volume legt:

docker exec homebridge hb-service add homebridge-tuya-platform

Nach der Plugin-Installation müssen Sie Homebridge neu starten. Das geht entweder über die Web-UI (Schaltfläche „Neustart“) oder per Terminal:

docker compose restart homebridge

Konfigurieren Sie das Plugin danach im automatisch erscheinenden Dialog der Web-UI oder in der config.json (Konfigurationseditor).

Verifizieren: Nach dem Neustart erscheinen neu eingebundene Geräte in der Home-App. Prüfen Sie 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

Konfiguration und Plugins bleiben im Volume erhalten. Plugin-Updates laufen separat über den Tab „Plugins“. Innerhalb des Containers eingespielte Updates von Homebridge, Web-UI oder Node.js überschreibt das nächste Image-Update.

Hinweis zu automatischen Updates: Watchtower ist für Homebridge offiziell nicht empfohlen (Stand 2025/2026), da automatische Image-Updates Plugin-Inkompatibilitäten auslösen können. Alternativen: Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich.

Sichern Sie das gesamte homebridge/-Verzeichnis. Das Unterverzeichnis .persist/ enthält den HomeKit-Pairing-State; geht es verloren, müssen Sie alle Geräte neu koppeln. Sichern Sie 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 ports: statt network_mode: host. Fix: network_mode: host setzen, ports: entfernen, Container neu starten.
Docker Desktop (macOS/Windows) – Bridge läuft, aber unsichtbar: mDNS/Bonjour erreicht durch die VM-Schicht das physische Netz nicht; ohne Workaround nur auf einem echten Linux-Host lösbar.
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: start_period: 300s nicht verkleinern; die Ersteinrichtung dauert bis zu 5 Minuten.
Bridge erreichbar, aber falsches Netzwerk-Interface für mDNS: Die HAP-Bibliothek wählt manchmal docker0 statt des physischen Interfaces. Fix: In der Web-UI unter „Einstellungen“ → „Netzwerkschnittstellen“ das physische Interface (z. B. eth0) auswählen oder einen anderen mDNS-Advertiser (Avahi, Ciao oder Bonjour) 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: .persist/ wurde gelöscht, der Pairing-State ist verloren. Fix: Re-Pairing, künftig homebridge/ regelmäßig 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. config.json, Pairing-Daten und Plugins liegen in einem Volume-Verzeichnis, ohne PostgreSQL, Redis oder MySQL. Für das Backup genügt das homebridge/-Verzeichnis.

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

Web-UI unter http://<server-ip>:8581 öffnen, in der Home-App „Zubehör hinzufügen“ → „Weitere Optionen“ wählen, QR-Code scannen oder PIN eingeben und die Warnung zum nicht zertifizierten Zubehör bestätigen (Schritt 5).

Funktioniert Homebridge auf einem Raspberry Pi?

Ja. Das offizielle Image unterstützt arm64v8 (Raspberry Pi 4/5 mit 64-Bit-OS) und arm32v7 (ältere Pis mit 32-Bit-OS); docker pull wählt die Architektur automatisch. Empfohlen ist Raspberry Pi OS 64-Bit.

Wie installiere ich neue Plugins?

Über den Tab „Plugins“ der Web-UI oder per docker exec homebridge hb-service add homebridge-<plugin-name>, danach Homebridge neu starten und das Plugin in der Web-UI konfigurieren (Schritt 6).

Kann ich mehrere HomeKit-Bridges mit Homebridge betreiben?

Ja. Seit Homebridge 1.3 laufen Plugins im Child-Bridge-Modus in eigenen Prozessen als separate HomeKit-Bridges; stürzt ein Plugin ab, bleibt der Rest stabil. Konfiguriert wird pro Plugin in der Web-UI.

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

Der Reihe nach: network_mode: host in der compose.yaml prüfen, docker compose logs homebridge auf Plugin-Fehler durchsehen, das physische Netzwerk-Interface in den Einstellungen wählen, mit avahi-browse -a -t den _hap._tcp-Dienst prüfen.

Fazit

Homebridge bindet heterogene Smart-Home-Geräte mit einem Docker-Container ohne Datenbank und über 2.000 Plugins in Apple HomeKit ein. Der einzige echte Stolperstein ist network_mode: host. Als breiteres Smart-Home-Fundament lässt sich Home Assistant mit Docker gut mit Homebridge kombinieren; für Zigbee-Geräte im Docker-Stack ergänzt Phoscon/deCONZ in Docker.

Weiterführende Anleitungen und Quellen

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