From 6c5e6e72029219ae68eaa06eb03388116bd56264 Mon Sep 17 00:00:00 2001 From: Tim Kaufmann Date: Fri, 24 Oct 2025 21:05:48 +0000 Subject: [PATCH] Initial commit: Docker Stack homebridge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .gitignore | 8 +++ README.md | 127 +++++++++++++++++++++++++++++++++++++ docker-compose.yaml | 47 ++++++++++++++ mounts/.gitkeep | 0 restore/fix-permissions.sh | 22 +++++++ 5 files changed, 204 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 docker-compose.yaml create mode 100644 mounts/.gitkeep create mode 100755 restore/fix-permissions.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f75eb0c --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# Ignore all data in mounts/ +mounts/* + +# Keep directory structure +!mounts/.gitkeep + +# Keep restore scripts +!restore/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..f515bd8 --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +# 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 +``` diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 0000000..c3cdabf --- /dev/null +++ b/docker-compose.yaml @@ -0,0 +1,47 @@ +services: + homebridge: + image: homebridge/homebridge:ubuntu + container_name: homebridge + restart: unless-stopped + + # Security Hardening + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + cap_add: + - CHOWN # Config file ownership + - SETUID # User switching in entrypoint + - SETGID # Group switching in entrypoint + - DAC_OVERRIDE # Permission override for config files + + # Resource Limits + deploy: + resources: + limits: + memory: 1G + cpus: '1.0' + pids: 200 + reservations: + memory: 256M + cpus: '0.25' + + stop_grace_period: 15s + + # macvlan Network - HomeKit mDNS Discovery + networks: + docker_macvlan: + ipv4_address: 10.11.1.243 + + environment: + - HOMEBRIDGE_CONFIG_UI=1 + - HOMEBRIDGE_CONFIG_UI_PORT=8581 + - TZ=Europe/Berlin + + volumes: + - ./mounts:/homebridge + +networks: + docker_macvlan: + external: true + name: docker_macvlan diff --git a/mounts/.gitkeep b/mounts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/restore/fix-permissions.sh b/restore/fix-permissions.sh new file mode 100755 index 0000000..66d23af --- /dev/null +++ b/restore/fix-permissions.sh @@ -0,0 +1,22 @@ +#!/bin/bash +# fix-permissions.sh - homebridge +set -e +RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m' + +echo -e "${YELLOW}🔧 Setze Permissions für homebridge...${NC}" + +# Prüfe sudo +[[ $EUID -ne 0 ]] && { echo -e "${RED}❌ Fehler: Mit sudo ausführen${NC}"; exit 1; } + +# Prüfe Verzeichnis +[[ ! -d "mounts" ]] && { echo -e "${RED}❌ Fehler: mounts/ nicht gefunden. Von /srv/docker/homebridge aus ausführen!${NC}"; exit 1; } + +# User Namespace Mapping +# Container UID 0 (root) → Host UID 100000 (unprivileged) + +echo " 📂 mounts/ → 100000:100000 (755)" +chown -R 100000:100000 ./mounts +chmod 755 ./mounts + +echo -e "${GREEN}✅ Permissions gesetzt${NC}" +echo "Wichtig: Container UID 0 → Host UID 100000 (userns-remap)"