Homebridge on Synology

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
• Installing Docker on Synology DSM
• Homebridge Package For Synology DSM
• Step 1: Download Docker Image
• Step 2: Create Container
• Step 3: Installing Plugins
  • Method 1: Using the command line
  • Method 2: Manually edit the package.json file
• Step 4: Customising config.json
• Viewing Homebridge Logs
• Opening Ports / Synology
• Connect iOS / HomeKit
• Scheduled Reboot / Synology
• Updating Homebridge on Synology

Requirements

• A Docker compatible Synology NAS
• Disk Station Manager 6+

Limitations

• Not suitable for HomeKit cameras. 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

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.

Make sure you select the latest tag:

2. Create Container

Launch a new container using the oznu/homebridge image.

Name your container appropriately and then click Advanced 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.

Click the Volume tab and then Add Folder.

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.

Set the Mount path to be /homebridge.

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.

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 -> Server name, it should contain no spaces or special characters.

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

3. Installing Plugins

Plugins are defined in the package.json file which will have been created in the Homebridge configuration folder defined in the above steps. There are a few different ways you can install plugins:

1. Using the command line
2. Manually updating the package.json file

Method 1: Command Line

Installing plugins via the command line is the easiest method to get the latest version of a plugin. To start a command line session with for your oznu/homebridge container click the Details tab:

Click the Terminal tab and then Create > Launch with command.

Enter the command sh. To keep the container size small bash is not installed.

Click on the new sh command option to spawn a prompt. You can now run the commands to install plugins.

To install a plugin, for example, homebridge-platform-wemo run this command:

npm install homebridge-platform-wemo

To remove a plugin:

npm uninstall homebridge-platform-wemo

After installing a plugin you need to restart the container to activate it. You can do this from the Overview tab. Adding and removing plugins using this method will automatically update the package.json file.

Method 2: Manually edit the package.json file

You can also install and remove plugins by editing your package.json file. To do this open and amend the file using a text editor of your choice.

The package.json file can be found in the Homebridge configuration folder we created in the above steps after you launch the container at least once.

If you choose to install plugins using this method make sure your JSON is formatted correctly. A missing or extra comma will prevent any plugins being installed.

Some editors like TextEdit on OSX will try and replace the " with non standard quotes which will cause issues - to avoid this use a plain text editor like Atom or Visual Studio Community.

You can use jsonlint.com to verify your package.json is syntactically correct.

To make sure the latest version of any plugin is installed use a *.

{
  "dependencies": {
    "homebridge-platform-wemo": "*",
    "homebridge-dummy": "*"
  }
}

You can delete plugins by removing them from the package.json file.

After editing the package.json file restart the Homebridge container to apply the changes.

4. Customizing config.json

Most Homebridge plugins require you to add additional configuration in the Homebridge config.json file which will have been created in the Homebridge configuration folder defined in the above steps.

You can open and edit the config.json in a text editor of your choice.

Some editors like TextEdit on OSX will try and replace the " with non standard quotes which will cause issues - to avoid this use a plain text editor like Atom or Visual Studio Community.

You can use jsonlint.com to verify your config.json is syntactically correct.

After editing the config.json file restart the Homebridge container to apply the changes.

Viewing Homebridge Logs

You can view the Homebridge logs using the Log tab.

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.

Scheduled Reboot

Optionally, you can schedule Synology to reboot homebridge at a convenient time such as the middle of the night.

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

Updating Homebridge on Synology

To update to the latest version of Homebridge and the oznu/homebridge container 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 that 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: /usr/local/bin/docker pull "oznu/homebridge"
4. When the image download is complete, go to the Container tab and start the homebridge container.