Tim Kaufmann
aebe9ad2de
Hybrid-DNS-Setup (127.0.0.11 + 10.11.1.1) ermöglicht: - Docker-interne Namensauflösung (Fallback) - Externe DNS-Abfragen über Gateway (10.11.1.1) - Konsistent mit ipsymcon-Stack Neue CLAUDE.md mit technischer Referenz für Debugging und Operations. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
181 lines
4.1 KiB
Markdown
181 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Container läuft?
|
|
docker compose ps
|
|
|
|
# Port gebunden?
|
|
docker compose logs --tail=20 | grep -i "listen\|port\|8581"
|
|
```
|
|
|
|
**Lösung:**
|
|
```bash
|
|
docker compose restart
|
|
```
|
|
|
|
---
|
|
|
|
## Monitoring
|
|
|
|
### Health Checks
|
|
|
|
```bash
|
|
# Container Status
|
|
docker compose ps
|
|
# Erwartung: "Up"
|
|
|
|
# Webinterface
|
|
curl -f http://10.11.1.243:8581/ || echo "FEHLER"
|
|
```
|
|
|
|
### Resource Monitoring
|
|
|
|
```bash
|
|
# 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)
|