Skip to content

Homebridge on Synology

Jump to bottom
Michael Bierman edited this page Nov 11, 2021 · 101 revisions

How to setup Homebridge & Docker on a Synology NAS

This guide will show you how to run the oznu/homebridge docker image on a Synology NAS running DSM 6.

Requirements

Limitations

  • The Docker container does not have access to the hardware video encoder.

Installing Docker on Synology DSM

You can install the Docker app using the Synology DSM Package Center.

Homebridge Package For Synology DSM

This method only works on DSM 6.x.x. If you are running DSM 7.x.x, skip this step and manually configure the container.

The easiest way to get Homebridge running on your Synology NAS is to use the Synology Homebridge Package.

  1. Download the latest .spk from here: https://github.com/oznu/homebridge-syno-spk/releases/latest
  2. Open Package Center in DSM and select the Manual Install option.
  3. Click Yes when warned about using a package from an unknown publisher.
  4. Create Homebridge File Share: Enter the path where you want Homebridge to store it's config, defaults to "/volume1/docker/homebridge".
  5. Select Image Type: Select Latest (todo add info on what implications on selecting Alpine vs Debian)
  6. Homebridge Config UI X: Select Yes.
  7. Confirm Settings: Select Run after installation. Click Apply.
  8. Installing... will be shown - the first time you install may take some time as the latest oznu/homebridge image is downloaded from Docker Hub.
  9. Use the Homebridge app icon in the main menu or if there is no icon then go to Homebridge in Package Manager and click the URL to access the Homebridge UI where you can manage your setup.

1. Download Docker Image

Open the Docker app on your Synology DSM, go to the Registry section and then search for and download the oznu/homebridge image.

Download oznu/homebridge docker image

Make sure you select the latest tag:

Select latest tag

2. Create Container

Launch a new container using the oznu/homebridge image.

Create container

Name your container appropriately and then click Advanced Settings:

General settings

Check the box to Enable auto-restart. This is recommended if you want your container to automatically restart after your Synology DSM reboots or if Homebridge crashes.

Advanced Settings

Click the Volume tab and then Add Folder.

Volumes

Create a new empty folder to store your Homebridge configuration in. This will allow you to update, delete and recreate the Homebridge container without loosing any plugins or configuration.

In case you need to reset your configuration, just empty the contents of this folder and restart the container.

Create folder

Set the Mount path to be /homebridge.

Volume mount

Click the Network tab and check the box to Use the same network as Docker host. This will allow the Homebridge to be discoverable by iOS and HomeKit on your local network.

Network settings

Click the Environment tab and add a new environment variable named DSM_HOSTNAME. The value of the DSM_HOSTNAME environment variable should exactly match the server name as shown under Synology DSM Control Panel -> Info Center -> Network -> Server name`, it should contain no spaces or special characters.

Environment variables

Click OK to save your advanced settings and then click Apply to start the oznu/homebridge container.

Summary

Complete: Login to the Homebridge UI

The container is now setup and ready for use.

You can access the Homebridge UI using http://IP_ADDRESS:8581, replacing IP_ADDRESS with the IP of your Synology server.

The default user is admin with password admin.

The Homebridge UI web interface will allow you to install, remove and update plugins, and modify the Homebridge config.json and manage other aspects of your Homebridge service.

Viewing Homebridge Logs

You can view the Homebridge logs using the Log tab. You may need these to see what is going on and it is helpful when filing a bug about homebridge.

view logs

You can export the logs in html or csv format from Synology.

Opening Ports / Synology

If you have a firewall set up on your Synology you must open the following ports to devices on your LAN using TCP or homebridge won’t be able to work properly with HomeKit:

Port Description
53036 Homebridge
8581 Homebridge interface
51827 Homekit Protocol (allows pairing homebridge to HomeKit)
5353 mDNS (without it, you get “No Response” from devices when lookups fail.)

See Control Panel > Security > Firewall > Edit Rules.

Connect iOS / HomeKit

You should now be able to see the Homebridge as a new HomeKit accessory in the Apple iOS Home App. You can pair the device using the default pin. You can change the pin by editing the config.json file.

Default Pairing Pin: 031-45-154

When using iOS 11 you will need to select Don't have a Code or Can't Scan and then under the Manual Code heading select the Enter code... link.

Home app add accessory

Scheduled Reboot

Optionally, you can schedule Synology to reboot homebridge at a convenient time such as the middle of the night. There are two methods for doing this.

Method 1

  1. Login to your Synology and open the Control Panel.
  2. Choose Task Scheduler.
  3. Choose Create and then Scheduled Task and User-defined Script.
  4. Under Task give it a name like, Reboot homebridge or whatever you like.
  5. Leave User set to root.
  6. Open the Schedule Tab and set whatever time you would like to run the reboot. Daily, weekly, etc. Note, Reboot takes about 40 seconds max.
  7. Open the Task Settings tab and enter the following. Note the part before && (all of line 2) will log all reboots to a file in your homebridge directory before the reboot occurs. You can skip that if you prefer. If you include it, make sure that permissions are set correctly for that file.
/bin/echo "$(date) rebooting homebridge..." >> 
/volume1/docker/homebridge/update.log && \
sudo /usr/local/bin/docker container restart homebridge

Task Scheduler

Method 2

Use this script instead of directly rebooting. This allows you to do other things such as automatically update plugins and randomize your login wallpaper.

Updating Homebridge on Synology

To update to the latest version of Homebridge and the oznu/homebridge container using the Synology docker client, go to the Docker app in Synology.

  1. On the Container tab stop the existing Homebridge container (Select the container, then Action > Stop).
  2. Edit the existing container and change it's name to homebridge-old.
  3. Go to the Image tab. Note the tag of the docker image you have been using. Probably latest. You will need to know this for the following steps.
  4. Delete that image. (Note Synology Docker may not let you delete the image if it is associated with a container. If that's the case, continue on to the next step.)
  5. Go to the Registry tab and find oznu/Homebridge by searching for oznu homebridge. Choose the same tag that you saw in the step above.
  6. Download the new Image
  7. When the image download is complete, go to the Container tab and select homebridge-old then click Settings then Duplicate settings.
  8. Rename the container homebridge.
  9. Start the homebridge container.
  10. Delete the homebridge-old container once you have confirmed everything is working.

Or - Use this process to update in place

(Make sure to have mapped the /homebridge folder to store your local configuration, as per the instructions above).

  1. On the Container tab, stop the existing Homebridge container (Select the container, then Action > Stop).
  2. Then Clear the image (Select the container, then Action > Clear). This will clear the image, your local configuration will still be in the /homebridge folder you mapped above.
  3. Login to your Synology DSM as execute this command to download the latest image: sudo /usr/local/bin/docker pull "oznu/homebridge"
  4. When the image download is complete, go to the Container tab and start the homebridge container.

Or - Use this process to update via terminal

sudo docker stop homebridge
sudo docker pull oznu/homebridge:latest
sudo docker start homebridge

Note, once you verify that your new homebridge container is running, you may want to run docker's prune command to get rid of code no longer in use.

sudo docker system prune

Major Node.js Version Updates

You should not try to upgrade the version of node.js in your local install. To upgrade Node.js you will need to download the latest version of the Docker image when it is ready. This can be done using the following commands in the section, Updating Homebridge on Synology.

Clone this wiki locally