From 0155c0af6f01f8654667658adc33412bc8394e7b Mon Sep 17 00:00:00 2001 From: ChillBill77 <129118422+ChillBill77@users.noreply.github.com> Date: Wed, 24 Jun 2026 21:40:25 +0200 Subject: [PATCH 1/4] Homebridge feature --- README.md | 1 + services/homebridge/.env | 18 ++++++ services/homebridge/README.md | 77 +++++++++++++++++++++++ services/homebridge/compose.tailscale.yml | 41 ++++++++++++ services/homebridge/compose.yml | 39 ++++++++++++ 5 files changed, 176 insertions(+) create mode 100644 services/homebridge/.env create mode 100644 services/homebridge/README.md create mode 100644 services/homebridge/compose.tailscale.yml create mode 100644 services/homebridge/compose.yml 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..0470824 --- /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" + - "443:443" + 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 From dda12b4fe13022249459969c1dd3fecd04986b6a Mon Sep 17 00:00:00 2001 From: ChillBill77 <129118422+ChillBill77@users.noreply.github.com> Date: Wed, 24 Jun 2026 21:55:30 +0200 Subject: [PATCH 2/4] Update compose.tailscale.yml --- services/homebridge/compose.tailscale.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/services/homebridge/compose.tailscale.yml b/services/homebridge/compose.tailscale.yml index 0470824..dcd4208 100644 --- a/services/homebridge/compose.tailscale.yml +++ b/services/homebridge/compose.tailscale.yml @@ -30,8 +30,8 @@ services: - sys_module restart: always ports: - - "5353:5353" - - "443:443" + # - "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 From bbc421d76161dbf2cebe64bdeda36d5fdef1d385 Mon Sep 17 00:00:00 2001 From: ChillBill77 <129118422+ChillBill77@users.noreply.github.com> Date: Sun, 28 Jun 2026 14:03:13 +0200 Subject: [PATCH 3/4] Update compose.yml Removed the Include --- services/homebridge/compose.yml | 38 ++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/services/homebridge/compose.yml b/services/homebridge/compose.yml index fab7b53..7532018 100644 --- a/services/homebridge/compose.yml +++ b/services/homebridge/compose.yml @@ -12,10 +12,42 @@ configs: {"Proxy":"http://127.0.0.1:8581"}}}}, "AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false}} -include: - - ./compose.tailscale.yml - 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 + homebridge: image: ${IMAGE_URL} network_mode: service:tailscale From ded9d3ae0f21a19b2064dede23860da3b381baff Mon Sep 17 00:00:00 2001 From: ChillBill77 <129118422+ChillBill77@users.noreply.github.com> Date: Sun, 28 Jun 2026 14:04:20 +0200 Subject: [PATCH 4/4] Delete services/homebridge/compose.tailscale.yml --- services/homebridge/compose.tailscale.yml | 41 ----------------------- 1 file changed, 41 deletions(-) delete mode 100644 services/homebridge/compose.tailscale.yml diff --git a/services/homebridge/compose.tailscale.yml b/services/homebridge/compose.tailscale.yml deleted file mode 100644 index dcd4208..0000000 --- a/services/homebridge/compose.tailscale.yml +++ /dev/null @@ -1,41 +0,0 @@ -# ============================================================================= -# 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'