[FEATURE] Homebridge feature

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
 

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

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.

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 <addr>:<port> 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'

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