From aebe9ad2dee8590afd9fe436034364ae37f0171b Mon Sep 17 00:00:00 2001 From: Tim Kaufmann Date: Sun, 26 Oct 2025 22:24:37 +0000 Subject: [PATCH] =?UTF-8?q?DNS-Konfiguration=20f=C3=BCr=20externe=20Aufl?= =?UTF-8?q?=C3=B6sung=20+=20Dokumentation=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CLAUDE.md | 180 ++++++++++++++++++++++++++++++++++++++++++++ docker-compose.yaml | 5 ++ 2 files changed, 185 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e2b2461 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,180 @@ +# 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) diff --git a/docker-compose.yaml b/docker-compose.yaml index c3cdabf..669248e 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -38,6 +38,11 @@ services: - HOMEBRIDGE_CONFIG_UI_PORT=8581 - TZ=Europe/Berlin + # DNS für macvlan - externe + interne Auflösung + dns: + - 127.0.0.11 # Docker-intern (Fallback) + - 10.11.1.1 # Gateway (externe Auflösung) + volumes: - ./mounts:/homebridge