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=homebridgecom.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
Officeplug 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 Birdcleanup. This checks controller reachability only; it does not prove HomeKit
control works.
homebridge added to the expected always-on cAdvisor container list.probe_success{service="Homebridge UI"} returned 1.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:
858110.0.0.24Disabled plugins:
homebridge-hue
Review Findings
The current setup is functional, but it is not the cleanest long-term shape for
this environment.
Positive signals:
4.1.2, which matches the latest Synologypackage release observed during the review.
currently a storage concern.
Concerns:
frequent than the official Docker image.
homebridge/homebridge Docker image is actively maintained andwas 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.
layout, dashboard expectations, or Docker backup/project-sync workflow.
This is not proof of compromise, but reinforces that the UI should remain
LAN-only and should use a strong password.
10.0.0.24:80.
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 becausethe host network already handles LAN presence. If HomeKit discovery behaves
badly after migration, this is one of the first settings to revisit.
/volume1/homebridge folder is mounted directly so HomeKitpairing and plugins should survive the move.
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:
http://10.0.0.119:8581.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
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:
serial, zone, irrigation-state, rain-sensor, and command-support responses.
showRequestResponse: true. This was changed to false.
NotAcknowledgedResponse for some follow-up calls. Plugin version 3.1.2
then failed on an unchecked seasonalAdjust.length read.
only reads .length when the seasonal-adjust response is an array.
parsed incorrectly. This was handled with a supported config option:
firmware: "2.10" for the 10.0.0.24 device.
configDeviceName of RainBird Controller was added so accessorynames 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:
/volume1/homebridge in Synology/container config backup coverage.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.