homebridge

Services

• homebridge: homebridge/homebridge:ubuntu - HomeKit Bridge für Apple Home
  • Web UI: http://10.11.1.243:8581
  • Netzwerk: docker_macvlan (10.11.1.243)
  • macvlan erforderlich für HomeKit mDNS/Bonjour Discovery

Backup-Strategie

Typ: GIT_PLUS_DATA

Was wird gebackupt

• Git-Repo: https://gitea.office.timkaufmann.de/tim/frasier-docker-homebridge
  • docker-compose.yaml
  • README.md
  • restore/fix-permissions.sh
• Daten-Backup: /srv/docker/homebridge/mounts/ → Nextcloud via rclone
  • config.json (HomeKit-Bridge Konfiguration)
  • accessories/ (HomeKit-Accessories Pairing-Daten)
  • persist/ (Plugin-Daten)
  • node_modules/ (Homebridge-Plugins)

Disaster Recovery

Schnellstart

# 1. Stack klonen
cd /srv/docker/
git clone git@gitea.office.timkaufmann.de:tim/frasier-docker-homebridge.git homebridge
cd homebridge

# 2. Daten wiederherstellen
# Siehe: /srv/docker/rclone/mounts/scripts/frasier-docker-homebridge/
# oder manuell:
# rclone copy nextcloud-encrypted:backups/frasier-docker-homebridge/latest/ ./mounts/

# 3. Permissions korrigieren
sudo bash restore/fix-permissions.sh

# 4. Stack starten
docker compose pull && docker compose up -d

Funktionstest

docker compose ps                    # Container running?
docker compose logs --tail=50        # Keine Fehler?
curl -I http://10.11.1.243:8581      # Web UI erreichbar?
# Apple Home App: Bridge sichtbar und verbunden?

Wichtige Notizen

• macvlan erforderlich: HomeKit-Geräte finden Bridge via mDNS/Bonjour im LAN
• User Namespaces: Container-Root läuft unprivileged (Host-UID 100000)
• Plugins: Über Web UI installierbar, persistieren in mounts/node_modules/
• HomeKit-Pairing: accessories/ enthält Pairing-Daten (kritisch!)

File Ownership & Permissions

Permissions nach Disaster Recovery wiederherstellen:

sudo bash restore/fix-permissions.sh

Script setzt korrekte User Namespace Mappings (Container UID 0 → Host UID 100000).

Troubleshooting

HomeKit-Bridge in Apple Home nicht sichtbar

Symptom: Bridge erscheint nicht in Apple Home App

Prüfen:

# Container läuft?
docker compose ps

# mDNS funktioniert?
docker exec homebridge avahi-browse -a -t
# → _hap._tcp sollte erscheinen

# macvlan IP erreichbar?
ping 10.11.1.243

Lösung:

• Container neustarten: docker compose restart
• iOS-Gerät muss im selben LAN sein (10.11.1.0/24)
• Bridge via QR-Code/Code in Apple Home App manuell hinzufügen

Web UI nicht erreichbar

Symptom: http://10.11.1.243:8581 antwortet nicht

Prüfen:

docker compose logs --tail=100 | grep -i "listening"
# → Sollte "Homebridge UI is listening on :: port 8581" zeigen

# Port-Check
docker exec homebridge netstat -tulpn | grep 8581

Lösung:

docker compose restart
# Falls weiterhin Probleme: Logs prüfen für Fehler
docker compose logs -f

Permission Denied Errors

Symptom: Container-Logs zeigen "EACCES" oder "Permission denied"

Lösung:

docker compose down
sudo bash restore/fix-permissions.sh
docker compose up -d