Skip to content

Running Homebridge on Firewalla Gold

Jump to bottom
tiefps edited this page Jan 13, 2024 · 114 revisions

This guide provides step-by-step instructions to show you how to install Homebridge on Firewalla Gold (GitHub), a multi-gigabit router and Firewalla Purple with a firewall and built in VPN server and client that runs on Ubuntu and so it can run lots of things, including Docker - with Homebridge.

Installing Homebridge

Note, currently this is only tested on Firewalla Gold and Purple 1.971 and later.

Step 1: Create Homebridge Storage Directory

Login to Firewalla via SSH.

The username is pi (and is unchangable). Your password is generated in the Firewalla app. Settings > Advanced > Configurations SSH Console

Create the Homebridge storage directory, and navigate to it:

# make homebridge storage directory
mkdir /home/pi/.firewalla/run/docker/homebridge/

# change directory
cd /home/pi/.firewalla/run/docker/homebridge/

Step 2: Create docker-compose.yml File

Create a new file named docker-compose.yml using your favorite editor (vi, vim, or nano) for example, by running:

nano docker-compose.yml

then enter the following:

version: '2'
services:
  homebridge:
    image: homebridge/homebridge:ubuntu
    container_name: homebridge
    restart: always
    network_mode: host
    environment:
      - PGID=1000
      - PUID=1000
      - HOMEBRIDGE_CONFIG_UI=1
      - HOMEBRIDGE_CONFIG_UI_PORT=8581
      - TZ=Australia/Sydney
      - ENABLE_AVAHI=0
    volumes:
      - '/data/homebridge:/homebridge'
    logging:
      driver: "json-file"
      options:
        max-size: "10m"

Note:

  • Firewalla changed their recommendation for where to map the /homebridge folder. Use the path above instead of the old recommendation. If you want to edit your config.json outside of the homebridge UI, go to /data/homebridge on firewalla.

  • Adjust the TZ option to match your current location - see list of timezones here.

  • You can change HOMEBRIDGE_CONFIG_UI_PORT to another port if you are already running something on port 8581.

Press CTRL+X to save the file and exit nano.

Step 3: Start Homebridge Container

Run the following commands to start Docker, ensure it starts again after a reboot, and to launch the Homebridge docker container:

# start docker
sudo systemctl start docker

# tell docker to start on boot
sudo systemctl enable docker

# bring up the Homebridge docker container
sudo docker-compose up -d

Verify the Homebridge container is running by running sudo docker ps:

sudo docker ps
# CONTAINER ID        IMAGE                    COMMAND             CREATED              STATUS              PORTS               NAMES
# cfb1c63c8b36        homebridge/homebridge:ubuntu   "/init"             About a minute ago   Up About a minute                       homebridge

Step 4: Login to the Homebridge UI

The container is now setup and ready for use. It may take a minute for the docker container to start and be ready to serve the web page.

You can access the Homebridge UI using http://FIREWALLA_LAN_IP_ADDRESS:8581.

If Firewalla is your DNS server, you can also try http://fire.walla:8581/.

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.

If you cannot get to the homebridge UI, make edits using your favorite text editor as shown in Step 5 mdns Settings. Edit the config.json file as shown in that step. And then see if the UI will be reachable.

Step 5: Set mdns Settings

mdns on Homebridge 1.3.0 and newer

Go to the "more options" (three dots) menu and open the Homebridge Settings menu. If you are running Homebridge 1.2.5 or older, skip to here.

Edit Network Interfaces under the Network section. You will want to choose the same Interface that your Home Hub (Apple HomePod or Apple TV) runs on. If you aren’t sure, go to firewalla and open the Hub device under Devices and note the Network name. In this case, it is LAN0. Yours may be called, simply LAN (which is the default firewalla name).

LAN0in this example is on 192.168.0.1 (Check Firewalla Network > LAN0)

So back in Homebridge, choose br0 and save (your option may look different).

Next go to mDNS Advertiser.

Choose Ciao if not already selected, and reatart homebridge.

Note If you had previously configured mDNS in Homebridge as described in the section below, edit your config.json to remove the mDNS section below.

For more details see mDNS Options.

mdns on Homebridge 1.2.5 and older

When running Homebridge on Firewalla, you need to set the mdns.interface options in Homebridge. This tells Homebridge to only advertise your internal / local IP address, rather than your public WAN address.

Using the Homebridge UI, go to the Config tab, under the first { add the following:

"mdns": { "interface": "FIREWALLA_LAN_IP_ADDRESS" },

Replace FIREWALLA_LAN_IP_ADDRESS with the internal / local IP address of your Firewalla device, then save the config by clicking Save.

⚠️ the interface should be the IP address of your Firewalla on your LAN. Often that is 192.168.0.1 but this will vary depending on how you configure it.

Step 6: Reset Homebridge

Within the Homebridge UI, use the drop down menu in the upper-right-corner to select Homebridge Settings and then choose Reset Homebridge Accessory.

Step 7: Add To HomeKit

  1. Open the Home app on your device.
  2. Tap the Home tab, then tap .
  3. Tap Add Accessory, then scan the QR code shown in the Homebridge UI on the Status tab.

Your bridge does not have any accessories yet, so you may receive a message saying Additional Set-up Required, this is ok, as you add plugins they will show up in the Home app without the need to pair again (except for Cameras and TVs).

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”.

Updating Homebridge

Updates to Homebridge can be done inside the container using the Homebridge UI, or by pulling down the latest version of the container:

# run these commands from the same directory you created the docker-compose.yml file in
cd /home/pi/.firewalla/run/docker/homebridge

# pull latest image
sudo docker-compose pull

# restart (if a new image was available)
sudo docker-compose up -d

After running these commands your Homebridge Docker container will automatically restart if there was an update available.

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

sudo docker system prune

Shell Access to your docker Container

If you require shell access to the container you can run:

sudo docker-compose exec homebridge sh

You can also access the containers terminal from the Homebridge UI, use the drop down menu in the upper-right-corner and select Terminal.

Optional Feature

Track firewalla CPU temperature

Bonus! If you want to track the CPU temperatures of firewalla in Homekit do this:

  1. Install the homebridge-linux-temperature plugin

  2. Add the following to the Accessory part of Homebridge config.json:

for Firewalla Gold:

{
  "accessory": "LinuxTemperature",
  "name": "Core 0 Temperature",
  "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp2_input",
  "divisor": 1000
},
{
  "accessory": "LinuxTemperature",
  "name": "Core 1 Temperature",
  "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp3_input",
  "divisor": 1000
},
{
  "accessory": "LinuxTemperature",
  "name": "core 2 Temperature",
  "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp4_input",
  "divisor": 1000
},
{
  "accessory": "LinuxTemperature",
  "name": "Core 3 Temperature",
  "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp5_input",
  "divisor": 1000
}

for Firewalla Purple:

{
"accessory": "LinuxTemperature",
"name": "Core 0 Temperature",
"sensor_path": "/sys/class/thermal/thermal_zone0/temp",
"divisor": 1000
},
{
"accessory": "LinuxTemperature",
"name": "Core 1 Temperature",
"sensor_path": "/sys/class/thermal/thermal_zone1/temp",
"divisor": 1000
}
  1. Restart homebridge

The temperature of your device will be displayed:

Scheduled Reboot

Optionally, you can schedule homebridge to reboot at a convenient time such as the middle of the night. There are two ways to do this.

Method 1

Do not just edit your crontab file on Firewalla or it will be wiped out every time you restart your Firewalla. Use the instructions below:

  1. Login to firewalla.
  2. Edit /home/pi/.firewalla/config/user_crontab using your favorite editor (vi, vim, or nano).
cd /home/pi/.firewalla/config
nano user_crontab
  1. Now add the following.
2 1 * * * sudo /usr/bin/docker container restart homebridge

In this example the homebridge container will restart at 1:02am nightly in your timezone. You can use a tool like this to adjust the time as you wish.

Now save the file and exit the editor.

The next time your firewalla reboots, it will add this to the system crontab file and homebridge will reboot when you asked it to.

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.

Configuration Reference

This table contains important information about your setup. You can use the information provided here as a reference when configuring or troubleshooting your environment after setting up Homebridge using the instructions below.

File Location / Command
Config File Path /homebridge/config.json (inside container shell)
Storage Path /homebridge (inside container shell)
Restart Command sudo docker restart homebridge
Stop Command sudo docker stop homebridge
Start Command sudo docker start homebridge
View Logs Command sudo docker logs -f homebridge
Clone this wiki locally