Homebridge Review And Docker Migration Plan

Last updated: 2026-05-28

Migration Status

The migration to Docker was performed on 2026-05-28.

Current runtime:

Runtime: Docker / Compose / Container Manager project
Compose project: homebridge
Container: homebridge
Image: homebridge/homebridge:latest
Project source: /volume1/docker/projects/homebridge-compose
Local source: synology/docker/projects/homebridge-compose
Config/appdata: /volume1/homebridge
Network mode: host
Restart policy: unless-stopped

The old Synology package was stopped by the user:

sudo /usr/syno/bin/synopkg stop homebridge

Post-cutover verification:

• Docker Compose reports project homebridge.
• The container has Compose labels:
• com.docker.compose.project=homebridge
• com.docker.compose.service=homebridge
• config file /volume1/docker/projects/homebridge-compose/compose.yaml
• Homebridge UI answered HTTP 200 on http://10.0.0.119:8581.
• Homebridge started on bridge port 51537.
• Homebridge loaded 33 cached accessories.
• Ring, TP-Link/Kasa, and Rain Bird plugins loaded.
• Ring connected to its socket.io server.
• TP-Link/Kasa detected the Office plug online.
• Rain Bird follow-up was completed after migration. Homebridge could reach the

controller at 10.0.0.24, but plugin version 3.1.2 exposed two

controller/plugin compatibility issues. Current mitigations are documented in

the Rain Bird section below.

Rollback archive created before cutover:

/volume1/docker/backups/homebridge/homebridge-before-docker-.tar.gz

The archive name is missing the timestamp because local PowerShell interpreted

the remote $(date ...) expression during backup creation. The archive itself

was created successfully and was about 83 MB.

Monitoring was updated after migration:

• Homebridge UI HTTP probe added to Prometheus service probes.
• RainBird Controller TCP probe added for 10.0.0.24:80 after the Rain Bird

cleanup. This checks controller reachability only; it does not prove HomeKit

control works.

• homebridge added to the expected always-on cAdvisor container list.
• Prometheus reload validation passed.
• probe_success{service="Homebridge UI"} returned 1.
• Expected-container count increased to 26.

Current State

Before the 2026-05-28 migration, Homebridge was installed as a third-party

Synology Package Center package, not as a Docker/Container Manager project.

Observed package details:

Package name: homebridge
Package version: 4.1.2
Package create time: 2025-03-27 21:01:39
Package source path: /var/packages/homebridge
Package target: /volume1/@appstore/homebridge
Package appdata/share: /volume1/homebridge
UI port: 8581
Homebridge bridge port: 51537

The package runs under the homebridge user and the active process was seen as:

homebridge

The Homebridge UI listens on:

tcp6 :::8581

The active config/share directory is:

/volume1/homebridge

Important files and folders in that directory:

config.json
package.json
auth.json
.ring.json
.uix-secrets
accessories/
persist/
backups/
node_modules/
homebridge.log

The persist/ and accessories/ folders are especially important because they

hold HomeKit identity, pairing, and accessory cache state. Do not discard them

during migration unless intentionally resetting Homebridge in Apple Home.

Installed Homebridge Components

Observed from /volume1/homebridge/package.json and installed

node_modules:

homebridge                                  2.0.2
homebridge-ring                             14.3.0
homebridge-tplink-smarthome                 8.0.4
@homebridge-plugins/homebridge-rainbird     3.1.2

Configured platforms:

• Homebridge UI / Config UI, port 8581
• TP-Link/Kasa smart home plugin
• Ring plugin, with a long refresh token stored in config
• Rain Bird plugin, controller at 10.0.0.24

Disabled plugins:

homebridge-hue

Review Findings

The current setup is functional, but it is not the cleanest long-term shape for

this environment.

Positive signals:

• Homebridge is running.
• The config is compact and easy to migrate.
• HomeKit identity files are present and can be preserved.
• The Synology package version is 4.1.2, which matches the latest Synology

package release observed during the review.

• Only a small number of Homebridge backups were observed; backup growth is not

currently a storage concern.

Concerns:

• The Synology package is third-party and package-level updates appear much less

frequent than the official Docker image.

• The official homebridge/homebridge Docker image is actively maintained and

was observed as recently updated.

• /volume1/homebridge files and folders are broadly writable

(rwx/Synology ACL style on several config files). A Docker migration can

preserve function while giving us a more explicit runtime boundary and a

documented Compose project.

• Homebridge is not currently represented in the Container Manager project

layout, dashboard expectations, or Docker backup/project-sync workflow.

• Recent logs showed a few failed Homebridge UI login attempts on 2026-05-21.

This is not proof of compromise, but reinforces that the UI should remain

LAN-only and should use a strong password.

• Recent logs showed Rain Bird controller connectivity failures to

10.0.0.24:80.

• Ring logs showed recurring socket reconnects and occasional outbound Ring API

timeouts. These can be normal cloud/network behavior, but should be monitored

if Ring devices feel unreliable in HomeKit.

Recommendation

Homebridge has now been moved into Docker/Container Manager. Keep the migration

rollback notes until the Docker runtime has proven stable for several days.

Current target:

Project name: homebridge
Project source: /volume1/docker/projects/homebridge-compose
Config/appdata: /volume1/homebridge
Image: homebridge/homebridge:latest
Network mode: host
Restart policy: unless-stopped

Use host networking. HomeKit and accessory discovery rely heavily on mDNS,

Bonjour, and broadcast/multicast behavior. A bridge network can work with extra

work, but host mode is the least surprising option on a single trusted LAN.

Do not run the package and Docker container at the same time. They would share

the same bridge identity, UI port, and HomeKit pairing state, and can confuse

Apple Home.

Proposed Docker Compose

Draft Compose file:

name: homebridge

services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: unless-stopped
    network_mode: host
    environment:
      TZ: America/New_York
      ENABLE_AVAHI: "0"
    volumes:
      - /volume1/homebridge:/homebridge
    labels:
      com.centurylinklabs.watchtower.enable: "true"

Notes:

• network_mode: host avoids mDNS discovery friction.
• ENABLE_AVAHI=0 is normally appropriate on Synology host networking because

the host network already handles LAN presence. If HomeKit discovery behaves

badly after migration, this is one of the first settings to revisit.

• The existing /volume1/homebridge folder is mounted directly so HomeKit

pairing and plugins should survive the move.

• The package should be stopped before the container starts.

Migration Runbook Reference

This was the safe migration order used for the cutover.

1. Confirm Homebridge is working before migration.

2. Export a Homebridge backup from the Homebridge UI if the UI is reachable.

3. Create a filesystem backup of /volume1/homebridge.

4. Capture the current package status and redacted config to the project.

5. Create /volume1/docker/projects/homebridge-compose/compose.yaml.

6. Stop the Synology Homebridge package.

7. Start the Docker project.

8. Confirm:

• Homebridge UI loads at http://10.0.0.119:8581.
• Apple Home still sees accessories.
• TP-Link/Kasa accessories respond.
• Ring accessories respond.
• Rain Bird accessories respond, or fail in the same way as before.

9. If successful, leave the Synology package installed but stopped for a short

rollback window.

10. After a few days of stable operation, decide whether to uninstall the

package. Do not uninstall until the Docker setup and backup are proven.

Rollback:

1. Stop the Docker homebridge project.

2. Start the Synology Homebridge package.

3. Confirm UI and Apple Home devices return.

Config Improvement Candidates

Access Control

• Keep Homebridge UI LAN-only.
• Do not expose Homebridge UI through the public reverse proxy.
• Use a strong UI password.
• Consider adding Homebridge UI reachability to Grafana as LAN-only monitoring,

but do not send content/secrets into metrics.

Rain Bird

The Rain Bird controller is at:

10.0.0.24:80

2026-05-28 findings:

• The iPhone Rain Bird app can talk to the controller.
• Homebridge can also talk to the controller; the logs showed successful model,

serial, zone, irrigation-state, rain-sensor, and command-support responses.

• The noisy request/response dump was caused by showRequestResponse: true.

This was changed to false.

• The controller reports support for some commands but then returns

NotAcknowledgedResponse for some follow-up calls. Plugin version 3.1.2

then failed on an unchecked seasonalAdjust.length read.

• A local compatibility patch was applied to the installed plugin file so it

only reads .length when the seasonal-adjust response is an array.

• The controller also returned a firmware-version response that the library

parsed incorrectly. This was handled with a supported config option:

firmware: "2.10" for the 10.0.0.24 device.

• A clean configDeviceName of RainBird Controller was added so accessory

names are no longer based on an undefined device name or the controller model

string with a hyphen.

Backups created on the NAS before changes:

/homebridge/backups/config.codex-rainbird-logcleanup-20260528145038.json
/homebridge/backups/Platform.HAP.js.codex-rainbird-seasonal-adjust-20260528145345
/homebridge/backups/config.codex-rainbird-firmware-override-20260528145711.json
/homebridge/backups/config.codex-rainbird-friendly-name-20260528145935.json

Local helper for reapplying the plugin patch after a Rain Bird plugin update:

powershell -NoProfile -ExecutionPolicy Bypass -File .\synology\docker\homebridge\Patch-HomebridgeRainBirdPlugin.ps1

If Rain Bird becomes noisy or unreliable again after an update, first confirm

whether the plugin patch is still present, then re-run the helper. If the

controller still works in the Rain Bird app but fails through Homebridge, treat

it as a plugin/controller compatibility issue before changing the network or

controller password.

TP-Link/Kasa

The current TP-Link config is discovery-based for plugs and bulbs. That is fine

if devices are on the same LAN/VLAN and discovery is reliable.

If devices disappear or respond slowly, move from broad discovery to explicit

device IPs/MACs after confirming the current Kasa device inventory.

Ring

The Ring plugin uses a long refresh token. Treat config.json, .ring.json,

and .uix-secrets as sensitive.

Socket reconnects are common with cloud integrations. If Ring devices are slow

or unreliable in Apple Home, gather a targeted log sample before changing the

plugin.

Backups

Observed Homebridge instance backups:

/volume1/homebridge/backups/instance-backups/

Backup files were small, about 33 KB each, and only a small set was observed.

No cleanup is needed right now.

Recommended long-term backup:

• Include /volume1/homebridge in Synology/container config backup coverage.
• Keep at least several recent Homebridge UI backups.
• Keep a migration backup before moving to Docker.

Snapshot Evidence

Read-only redacted review snapshot:

synology/docker/homebridge-review/20260528-101421/homebridge-redacted-review.txt

The snapshot redacts tokens, PINs, usernames, passwords, and similar sensitive

fields. Treat it as private infrastructure documentation anyway.