- This is a tech doc only for Pros.
- This is for Firewalla Gold, Purple, or Blue Plus.
- Incorrect settings of port forwarding will result in ports being opened on your WAN interface.
Thanks to Michael Bierman for his effort on this topic to sort everything out.
Homebridge is a server you can run on your home network that can connect many devices that aren't certified to work with Apple Homekit. It is a bridge between HomeKit and these devices which allows you to use Siri to control them.
1. Login to Firewalla via SSH. You will find the credential on your Firewalla app, Settings > Advanced > Configurations > SSH Console. The username is always, "pi"
2. Create the file,
# make homebridge storage directory mkdir /home/pi/.firewalla/run/docker/homebridge/ # change directory cd /home/pi/.firewalla/run/docker/homebridge/
# edit with your favorite editor, like vi
Add the following to
version: '2' services: homebridge: image: oznu/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'
- Adjust the
TZoption to match your current location - see list of timezone names here.
- If you are running something else on port 8080, change
HOMEBRIDGE_CONFIG_UI_PORTto another port.
- Note YAML only supports space characters for indents, not tabs. Use either two or four spaces for each level of indent as you prefer.
3. Run the following commands to install and start HomeBridge:
cd /home/pi/.firewalla/run/docker/homebridge sudo systemctl start docker sudo docker-compose up --detach
You can run this command and confirm the homebridge container running in docker.
sudo docker ps # CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES # cfb1c63c8b36 oznu/homebridge:ubuntu "/init" About a minute ago Up About a minute homebridge
5. Go to the "more options" (three dots) menu and open the
Homebridge, Settings menu and find Network.
If you open Homebridge's Network Interfaces you will see all of Firewalla's network interfaces. Choose the one that contains your Apple TV or HomePod as homebridge needs to connect to them.
Save when done.
6. Click restart on the upper right corner and you should be able to pair HomeBridge with your HomeKit (Home app) now.
The docker service and homebridge container won't automatically start after a system reboot, to do so, create the following folder and file
mkdir /home/pi/.firewalla/config/post_main.d/and add this to start_homebridge.sh
sudo systemctl start docker sudo systemctl start docker-compose@homebridge
now docker and homebridge will automatically start when Firewalla reboots.
To Check Docker Containers
sudo docker logs homebridge
This lets you confirm how the startup went, what port you are running on, and tons of other diagnostic information.
To Reset Docker Containers
In case the docker service doesn't start, please follow this guide to reset your docker service.
Tracking Firewalla CPU temperature
Here's an example of a plugin that adds some monitoring of Firewalla itself in Homekit. If you want to track the CPU temperatures of firewalla in Homekit:
Install the homebridge-linux-temperature plugin
Add the following to the Accessory part of Homebridge
"name": "Firewalla Core Temp",
"name": "Firewalla Core 0 Temp",
"name": "Firewalla Core 1 Temp",
"name": "Firewalla Core 2 Temp",
"name": "Firewalla Core 3 Temp",
Note that this plugin does not currently work with Firewalla Purple. The sensor path is as follows in case it gets fixed in the future.
And you can see FIrewalla's CPU temperatures in Homekit (Eve app shown below.)
Docker Configuration Reference
This table contains important commands to help you manage your docker container.
|File Location / Command|
|Config File Path||
|View Logs Command||
Updating Homebridge docker
sudo docker container stop homebridge && sudo docker container rm homebridge
sudo docker-compose up -d
sudo docker ps
Important Note: Preserve Resources
Docker containers can range from small to fairly large and the upgrade process means downloading a new image before deleting the old container. So be sure to use docker prune to get rid of unused containers and images or you may easily run out of space on Firewalla.
sudo docker system prune
On ubuntu 22.04 and later, when docker starts up, it may load a kernel module
br_netfilter which conflicts with ubuntu 22.04 if you are using Smart Queue. Dockers managed by Firewalla will automatically handle this, but if you create docker instance, you may need to run:
sudo rmmod br_netfilter
after starting docker service or the firewalla routing function may break.
This is due to a Linux Kernel bug which we plan to fix in our 1.976 release.
All product names, logos, and brands are the property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.
Bonus! If you want to track the CPU temperatures of firewalla in Homekit do this:
"name": "Core 0 Temperature",
"name": "Core 1 Temperature",
"name": "core 2 Temperature",
"name": "Core 3 Temperature",
What is the trick to get the port to attach to the container? I have 2 other containers running but when I compose this one, it won't attach to a port.
Have you tried https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold ?
Yes I just cross referenced the two docs, it's ignoring the parameter to change my port. It looks like the port change setting is also ignored in your yaml. In your pictures it looks like you're going back to 80. Have you tried this on a Firewalla with other containers running on 80?
I'll see if I can drop into bash in the container and see what's going on with the config.json.
Odd, when I drop into the container and cat out the config.json, the port change works but it's not resolving in the web address. So I decided to use ubuntu as the container image so I could run lsof to see if the port was listening in. Turns out it's listening but getting reset somewhere (see the connection refusal from the walla).
Then I tried looking up IP tables to see if I could find the culprit, but that's over my head.
Did you set the
This is critical.
The instructions seem to indicate you use the web UI to do this but I cannot get to the web UI.
You can use the webui if it is running or just edit the config.json via terminal.
Note, I have only tested this with the Alpine docker image. I can't guarantee it works the same on other architectures.
I've tried both images. For whatever reason I can't access 8080 or any other port I try to change. Does your setup have all 3 containers running (pi-hole, cloudflared, homebridge?).
Delete “persist” and “accessories“ dirs in the `/home/pi/.firewalla/run/docker/homebridge/homebridge` directory
The default homebridge user is **`admin`** with password **`admin`**.
If Homebridge works, start the other containers and test them. If there is a problem is is likely because of conflicting ports.
Let me know heat happens. If it doesn’t work, post your config.json here.
Okay - we are jamming. It's hard to say what fixed it, but I did have to clean up some space and remove some docker images. Thanks for your help!
If you can, please use /data for docker and docker images. We have seen people storing a lot of stuff in ~/. so please be careful
+1. I see no downside to using docker and potential issues if you don't!
I would just add that you should use docker prune as you upgrade to get rid of any residual garbage that gets left behind when updating your containers.
@Firewalla I agree but I followed the directions according to the docs. Note that /var/lib/docker is actually mounted on a mmc block partition that is 1.6GB. The /data dir looks to be mounted to the same block device but the partition is 3.6G. I believe this was by factory default during docker installation. Does the documentation need to be modified to move the docker install? Side note - I could/should mount an external drive.
@Michael and I agree re: prunning! I cleaned up some of the images this way.
I have updated the Github tutorial. with the new /data/homebridge path and new screenshots, etc.
@Firewalla any reply to @Danny Natale's question?
Note, the mDNS a instructions here have changed in Homebridge 1.3.0. See new instructions.
HomeBridge on Portainer Install Instructions:
NOTES: Be sure to change TZ below to your local timezone, and don't forget this will fire up on 8581 according to the setup below.
Here's the quick link on your local network assuming your firewalla is at the default address:
Here's my Stack (yaml) script:
I'm running into an error on step 3. I've verified my yaml file is correct. This is what I'm getting:
Any ideas what to do next?
Does your yaml file look like this?
Also, have you validated your yaml file? use something like https://yamlvalidator.com
I ran my yaml file through that link and it returned no errors. My file looks like what you posted, but the indentation is less (see picture, the indentation doesn't show up in the code when I paste it here)
This is the error I continue to have:
My understanding is this error usually has to do with either mistakes in spacing, tabs, or quotations. I don't see anything wrong with your quotes so I think it may be spaces or tabs.
Check to make sure the copy in Firewalla has no tabs. Replace tabs any with spaces. Make sure that the same number of spaces for each tab equivalent. So if one tab is 4 spaces two tabs is 8 spaces. Each "tab" has to be a minimum of two spaces.
If you want to copy directly from the example, you can use ":set paste" first, then copy from above and paste into vi. Then save and try again.
Thanks - I will try ":set paste" - I checked the code and didn't find any tabs. I actually typed the code and the spacing was done automatically by vi.
Thank you! ":set paste" and copying the code worked! I ran the diff command and saw some "23c23" in the old file (not visible, but I guess is there somewhere?) - Anyway, Thank you again!
How i can delete the homebridge installation and rest of config i've done to install homebridge?
@cybermaster69 there's an uninstall at github.com/mbierman/homebridge-installer
thanks, i would like to know if is possible to install home assistant and if there is a guide available. thanks
Please sign in to leave a comment.