Installing Homebridge on RaspberryPi with Docker

Homebridge is a lightweight NodeJS server you can run on your home network that emulates the iOS HomeKit API. It supports Plugins, which are community-contributed modules that provide a basic bridge from HomeKit to various 3rd-party APIs provided by manufacturers of “smart home” devices.

While it is possible to install homebridge on a linux server, keeping up with updates, dependency requirements, configuration changes, etc. can be come troublesome. Enter homebridge with docker. Installing homebridge with docker allows for a hassle-free installation and maintenance, and the ability to quickly move the installation to another server if needed.

In order to install homebridge, we need to create the environment for it as follows:

cd ~/docker-compose
mkdir homebridge
cd homebridge
vim docker-compose.yml

This will create a compose file inside the homebridge folder. After this, while in the vim interface, press INSERT or the letter i to enter insert mode, and paste the following compose definition. In YAML syntax the spaces matter.

version: '3.2'
services:
  homebridge:
    image: oznu/homebridge:raspberry-pi
    restart: always
    container_name: homebridge
    volumes:
      - /root/docker-persist/homebridge:/homebridge
    environment:
      - TZ=America/Chicago
      - HOMEBRIDGE_DEBUG=1
      - HOMEBRIDGE_INSECURE=1
      - HOMEBRIDGE_CONFIG_UI=1
      - HOMEBRIDGE_CONFIG_UI_PORT=8080
    network_mode: host

Save the file by pressing ESC and then typing :x and pressing ENTER. After saving, start the container by executing:

docker-compose up -d

The command will start homebridge as a service on port as a permanent service on port 51826 (default homebridge port), and a web management UI on port 8080. You will be able to access the management UI it by opening a browser and going to http://localhost:8080 (if on the raspberry pi), or http://raspberrypi:8080 if connecting from another machine in the network.

For more information on environment variables and configuration, visit the official oznu/homebridge page.

In order to configure homebridge, navigate to the Config section of the UI interface. You will be presented with a text area where you can add your configurations in JSON format. Make sure to enter valid JSON data, in the sections they belong.

After changing the configuration, you can restart the service by clicking the “power” button on the top right-hand corner.

In order to remove cached accessory configurations which sometimes can cause problems:

cd ~/docker-compose/homebridge
docker-compose down
rm -rf ~/docker-persist/homebridge/accessories
docker-compose up -d

Restarting the container will take a while. You can check its status on portainer. Be very careful in using the correct folder (docker-persist) when deleting the accessories folder. After executing this, homebridge will be restarted and the cache recreated with what is specified in the config.