# 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
```