diff --git a/README.md b/README.md index 2a8cb0c..b4cc9a9 100644 --- a/README.md +++ b/README.md @@ -203,6 +203,7 @@ ScaleTail provides ready-to-run [Docker Compose](https://docs.docker.com/compose | 🏠 Service | 📝 Description | 🔗 Link | | -------------------- | ---------------------------------------------------------------------- | ---------------------------------- | | 🏡 **Home Assistant** | An open-source home automation platform for controlling smart devices. | [Details](services/home-assistant) | +| **Home Bridge** | Homebridge is a lightweight Node.js server that emulates the HomeKit API. | [Details](services/homebridge) | ### 📱 Utilities diff --git a/services/homebridge/.env b/services/homebridge/.env new file mode 100644 index 0000000..827da40 --- /dev/null +++ b/services/homebridge/.env @@ -0,0 +1,18 @@ +# ============================================================================= +# Homebridge + Tailscale Sidecar Environment +# Copy to .env and fill values. Keep TS_AUTHKEY secret! +# ============================================================================= + +# --- REQUIRED: Tailscale --- +# Get a reusable or ephemeral auth key from https://login.tailscale.com/admin/settings/keys +# Recommended: auth key with "reusable" + "ephemeral" for containers, tagged if using ACLs +TS_AUTHKEY=tskey-auth-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + +# --- REQUIRED: Service identity --- +SERVICE=homebridge +IMAGE_URL=homebridge/homebridge:latest + +# --- Common container settings --- +TZ=Europe/Amsterdam +PUID=1000 +PGID=1000 diff --git a/services/homebridge/README.md b/services/homebridge/README.md new file mode 100644 index 0000000..151d132 --- /dev/null +++ b/services/homebridge/README.md @@ -0,0 +1,77 @@ +# homebridge with Tailscale Sidecar + +This Docker Compose configuration sets up [Homebridge](https://github.com/homebridge/homebridge) with Tailscale as a sidecar container. Homebridge emulates the iOS HomeKit API, enabling HomeKit integration for non-Apple smart home devices. The Homebridge UI is reachable **only over your Tailnet** via HTTPS. + +## ⚠️ Critical Limitation + +**Homebridge requires `host` network mode for HomeKit mDNS discovery.** This sidecar configuration isolates Homebridge into a separate network namespace, which **breaks HomeKit discovery entirely**. HomeKit clients will not be able to find or control your devices. + +**What works:** +- Access the Homebridge UI web interface over HTTPS via Tailnet: `https://homebridge.your-tailnet.ts.net` +- Install plugins, edit config, view logs +- Full remote administration + +**What doesn't work:** +- HomeKit device discovery on your local network +- HomeKit app integration from iPhone/iPad +- Siri control via HomeKit + +If you need HomeKit discovery, run Homebridge with `network_mode: host` instead (standard Docker setup, no Tailscale sidecar). If you only need the web UI for administration from Tailnet, proceed with this configuration. + +## About Homebridge + +Homebridge is a lightweight Node.js server that emulates the HomeKit API. It translates between HomeKit and non-HomeKit smart home devices (Philips Hue, IKEA TRADFRI, etc.), allowing them to integrate into the Apple Home ecosystem. This image includes FFmpeg with libfdk-aac for camera streaming support. + +## Architecture + +- `tailscale`: Runs the Tailscale client, obtains a Tailnet IP, serves HTTPS on :443 proxying to Homebridge UI on internal port 8581. +- `homebridge`: Runs in the **same network namespace** as the tailscale container. Configuration and plugins persist in a dedicated volume. + +Access the UI at: `https://homebridge.your-tailnet.ts.net` (after auth and healthy state). + +## Prerequisites + +- Docker & Docker Compose v2.20+ +- Tailscale account + ability to create auth keys +- Host user in `docker` group (or use sudo) +- Pre-create volume directories (recommended): + ```bash + mkdir -p homebridge-data/config ts-homebridge-state + ``` + +## First Run & Setup + +On first boot, Homebridge generates a unique setup code in the logs. Find it with: +```bash +docker compose logs homebridge | grep -i "setup code" +``` + +You'll use this code if setting up HomeKit bridges (only if HomeKit discovery were enabled). For web UI access, no setup code is needed. + +## Configuration + +### Important Notes + +- **ENABLE_AVAHI=0**: Avahi (mDNS daemon) is disabled since the sidecar network prevents proper mDNS broadcasts. HomeKit discovery is not functional in this setup. +- **Tailscale Serve**: The sidecar automatically proxies port 443 to the Homebridge UI on 8581. HTTPS certificates are auto-provisioned by Tailscale. +- **Plugins**: Install via the Homebridge UI. They persist in the mounted volume. + +### Optional Environment Variables + +Add to `compose.yml` under the `homebridge` service `environment:` block if needed: +- `HB_PORT=8581` — Web UI port (change if desired, but update compose.tailscale.yml Proxy port to match) + +## Upstream Documentation + +- [Homebridge GitHub](https://github.com/homebridge/homebridge) +- [Homebridge Docker Guide](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker) +- [Homebridge Plugins](https://www.npmjs.com/search?q=homebridge-plugin) +- [Homebridge UI](https://github.com/homebridge/homebridge-config-ui-x) +- [Tailscale Docker Guide](https://tailscale.com/blog/docker-tailscale-guide) + +## Troubleshooting + +- **Container unhealthy**: Check `docker compose logs tailscale` and `docker compose logs homebridge` +- **Can't reach UI over HTTPS**: Verify Tailscale connection with `docker compose exec tailscale tailscale status`. If not logged in, check TS_AUTHKEY. +- **UI timeout or 502**: Ensure Homebridge is running with `docker compose logs homebridge`. Check that internal port 8581 is correct. +- **HomeKit discovery not working**: This is expected. The sidecar breaks mDNS. Run with `network_mode: host` for full HomeKit support. \ No newline at end of file diff --git a/services/homebridge/compose.tailscale.yml b/services/homebridge/compose.tailscale.yml new file mode 100644 index 0000000..dcd4208 --- /dev/null +++ b/services/homebridge/compose.tailscale.yml @@ -0,0 +1,41 @@ +# ============================================================================= +# Reusable Tailscale Sidecar (shared with other services) +# Serves HTTPS on :443 proxying to app port via Tailscale Serve +# ============================================================================= + +services: + tailscale: + image: tailscale/tailscale:latest + container_name: ts-${SERVICE} + hostname: ${SERVICE} + environment: + - TS_AUTHKEY=${TS_AUTHKEY} + - TS_STATE_DIR=/var/lib/tailscale + - TS_SERVE_CONFIG=/config/serve.json # Tailscale Serve configuration to expose the web interface on your local Tailnet - remove this line if not required + #- TS_USERSPACE=false + - TS_ENABLE_HEALTH_CHECK=true # Enable healthcheck endpoint: "/healthz" + - TS_LOCAL_ADDR_PORT=127.0.0.1:41234 # The : for the healthz endpoint + #- TS_ACCEPT_DNS=true # Uncomment when using MagicDNS + - TS_AUTH_ONCE=true + configs: + - source: ts-serve + target: /config/serve.json + volumes: + - ./config:/config # Config folder used to store Tailscale files - you may need to change the path + - ./ts/state:/var/lib/tailscale # Tailscale requirement - you may need to change the path + devices: + - /dev/net/tun:/dev/net/tun # Network configuration for Tailscale to work + cap_add: + - net_admin + - sys_module + restart: always + ports: + # - "5353:5353" #Receive mDNS but does not do anything for Apple HomeBridge + # - "443:443" #Uncomment for local acces + healthcheck: + test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:41234/healthz"] # Check Tailscale has a Tailnet IP and is operational + interval: 1m # How often to perform the check + timeout: 10s # Time to wait for the check to succeed + retries: 3 # Number of retries before marking as unhealthy + start_period: 10s # Time to wait before starting health checks + #entrypoint: sh -c 'tailscaled -tun=userspace-networking & sleep 2 && tailscale up --authkey=${TS_AUTHKEY} --hostname=${SERVICE} && tailscale serve https:443 http://127.0.0.1:8581 & wait' diff --git a/services/homebridge/compose.yml b/services/homebridge/compose.yml new file mode 100644 index 0000000..fab7b53 --- /dev/null +++ b/services/homebridge/compose.yml @@ -0,0 +1,39 @@ +# ============================================================================= +# Homebridge + Tailscale Sidecar Compose +# WARNING: This config breaks HomeKit discovery. See README for details. +# Always validate with: docker compose config +# ============================================================================= +configs: + ts-serve: + content: | + {"TCP":{"443":{"HTTPS":true}}, + "Web":{"$${TS_CERT_DOMAIN}:443": + {"Handlers":{"/": + {"Proxy":"http://127.0.0.1:8581"}}}}, + "AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false}} + +include: + - ./compose.tailscale.yml + +services: + homebridge: + image: ${IMAGE_URL} + network_mode: service:tailscale + container_name: app-${SERVICE} + environment: + - PUID=${PUID} + - PGID=${PGID} + - TZ=${TZ} + - ENABLE_AVAHI=0 + volumes: + - ./${SERVICE}-data/config:/homebridge + depends_on: + tailscale: + condition: service_healthy + healthcheck: + test: ["CMD", "curl", "-f", "http://127.0.0.1:8581"] + interval: 60s + timeout: 10s + retries: 3 + start_period: 30s + restart: always