Tim Kaufmann
6c5e6e7202
- HomeKit Bridge für Apple Home - macvlan Netzwerk (10.11.1.243) für mDNS/Bonjour - Security: User Namespaces, cap_drop: ALL, resource limits - Backup-Strategie: GIT_PLUS_DATA 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
128 lines
3.1 KiB
Markdown
128 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
docker compose down
|
|
sudo bash restore/fix-permissions.sh
|
|
docker compose up -d
|
|
```
|