frasier-docker-homebridge/CLAUDE.md

Homebridge - Technical Reference

Für: LLM-Debugging, Konfiguration, Operations

HomeKit Bridge Docker Stack - ermöglicht Apple HomeKit Integration für Smart-Home-Geräte.

Kritikalität: Mittel - Nur für HomeKit-Nutzer relevant.

---

Architecture

Container Details

• Image: homebridge/homebridge:ubuntu
• Network: macvlan docker_macvlan (eigene LAN-IP für mDNS/Bonjour Discovery)
• IP-Adresse: 10.11.1.243 (statisch)
• Webinterface: Port 8581 (Config UI)
• User Namespaces: Aktiv (Container UID 0 → Host UID 100000)
• Data Volume: ~50-100 MB (Config + Plugins)

Netzwerk-Konfiguration

macvlan-Details: Siehe /srv/docker/CLAUDE.md → Section "macvlan Network Configuration"

Homebridge nutzt:

• IP: 10.11.1.243
• Netzwerk: docker_macvlan (shared mit ipsymcon und anderen Containern)
• mDNS/Bonjour: Für HomeKit Accessory Discovery (Port 5353)

DNS-Konfiguration (hybrid):

• 127.0.0.11 - Docker-interne Auflösung (Fallback)
• 10.11.1.1 - Gateway-DNS (externe Auflösung)
• Ermöglicht externe DNS-Abfragen über Gateway, behält Docker-interne Namensauflösung

Volume Mapping

./mounts       → /homebridge   # Alle Konfigurationen
  ├── config.json              # Homebridge Hauptkonfiguration
  ├── .homebridge/              # Plugin-Verzeichnis
  ├── persist/                  # Persistente Daten
  └── logs/                      # Logdateien

---

Common Operations

Container Management

# Start/Stop
docker compose up -d
docker compose down

# Logs ansehen
docker compose logs -f
docker compose logs --since 24h | grep -iE "error|warning"

# Status prüfen
docker compose ps
docker stats homebridge

Webinterface

Erreichbar unter: http://10.11.1.243:8581/

Standard Login: Siehe Homebridge Dokumentation oder Docker-Logs für initialen Setup-Code.

Permission-Probleme

Symptom: Config nicht lesbar/schreibbar.

Lösung:

docker compose down
sudo chown -R 100000:100000 ./mounts
docker compose up -d

---

Integration mit IP-Symcon

Falls IP-Symcon als "Quelle" genutzt wird (HomeKit Bridge für ipsymcon-Devices):

1. Plugin: Benötigt entsprechendes Plugin in Homebridge
2. Netzwerk: Beide nutzen macvlan, können sich aber via IP erreichen:
   • IP-Symcon: 10.11.1.242
   • Homebridge: 10.11.1.243
3. Konfiguration: In homebridge config.json entsprechendes Accessory/Bridge Plugin konfigurieren

---

Troubleshooting

mDNS/Bonjour Discovery funktioniert nicht

Symptom: HomeKit kann Homebridge nicht finden.

Diagnose:

# mDNS-Traffic sniffer
docker exec homebridge tcpdump -i eth0 -n udp port 5353 2>/dev/null || echo "tcpdump nicht verfügbar"

# Logs prüfen
docker compose logs --tail=50 | grep -iE "mdns|bonjour|advertise"

Lösungen: Siehe /srv/docker/ipsymcon/CLAUDE.md → Section "Troubleshooting" → "Discovery-Probleme (mDNS/UPnP)"

Webinterface nicht erreichbar

Symptom: Kann nicht auf 10.11.1.243:8581 zugreifen.

Diagnose:

# Container läuft?
docker compose ps

# Port gebunden?
docker compose logs --tail=20 | grep -i "listen\|port\|8581"

Lösung:

docker compose restart

---

Monitoring

Health Checks

# Container Status
docker compose ps
# Erwartung: "Up"

# Webinterface
curl -f http://10.11.1.243:8581/ || echo "FEHLER"

Resource Monitoring

# Resource Usage
docker stats homebridge --no-stream

# Disk Usage
du -sh ./mounts/

---

Security-Architektur

Stack folgt /srv/docker/CLAUDE-SECURITY.md:

• User Namespaces: Container-Root (UID 0) → Host UID 100000
• Capabilities: CHOWN, SETUID, SETGID, DAC_OVERRIDE
• no-new-privileges: true
• Resource Limits: 1GB RAM, 1.0 CPU, 200 PIDs

---

Related Documentation

• Security Guidelines: /srv/docker/CLAUDE-SECURITY.md
• Docker Operations: /srv/docker/CLAUDE.md
• IP-Symcon Integration: /srv/docker/ipsymcon/CLAUDE.md
• Homebridge Docs: https://homebridge.io/
• Homebridge Config: https://github.com/homebridge/homebridge/wiki

---

Installation Datum: 2025-10-26 (DNS-Konfiguration aktualisiert)