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