Installing Homebridge on RaspberryPi with Docker [bkraul's wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{:linux:homebridge-logo.png?nolink&200|}}
====== 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.
===== Creating the container =====
<callout type="info" title="Important" icon="true">This guide assumes there is a working RaspberryPi docker installation, per [[linux:installing_docker_on_raspberrypi|this guide]], and the user executing the commands is ''root'' (usually by executing ''sudo su'').</callout>
In order to install homebridge, we need to create the environment for it as follows:
<code bash>
cd ~/docker-compose
mkdir homebridge
cd homebridge
vim docker-compose.yml
</code>

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.
<code yaml>
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
</code>

Save the file by pressing ''ESC'' and then typing '':x'' and pressing ''ENTER''. After saving, start the container by executing:
<code bash>
docker-compose up -d
</code>

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. 

{{:linux:hb-ui.png?nolink&400|}}

For more information on environment variables and configuration, visit the official [[https://hub.docker.com/r/oznu/homebridge/|oznu/homebridge]] page.

===== Configuring homebridge =====
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.

===== Removing cached accessory configurations =====
==== Method 1: At the docker host level ====
In order to remove cached accessory configurations which sometimes can cause problems:
<code bash>
cd ~/docker-compose/homebridge
docker-compose down
rm -rf ~/docker-persist/homebridge/accessories
docker-compose up -d
</code>
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.