Please note:
- This is a tech doc for advanced users. Specific docker containers are not formally supported by Firewalla. We recommend checking with other Firewalla users or experts on individual docker containers if you have trouble.
- Installing Homebridge on Firewalla Gold series boxes should work o.k. at this time. Installing on Firewalla Purple series boxes and below is not recommended due to disk and memory limitations. If you have a Firewalla Purple box we recommend running Homebridge somewhere else. This can be a computer, Raspberry Pi, NAS, etc.
- Incorrect settings of port forwarding may result in ports being opened on your WAN interface.
- It is best to run this container outside in external storage; avoid over loading firewalla internal storage.
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, /home/pi/.firewalla/run/docker/homebridge/docker-compose.yaml.
# 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
vi /home/pi/.firewalla/run/docker/homebridge/docker-compose.yaml
Add the following to docker-compose.yaml
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"-
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 the logging options are recommended to prevent using up all your valuable space on your Firewalla. (see https://github.com/homebridge/docker-homebridge/issues/399)
- 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 homebridge/homebridge:ubuntu "/init" About a minute ago Up About a minute homebridge5. 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. Note you may see bonds as shown below if you are using LAG or, bridges if you are not. Either way, you can simply choose the IP of the network you are running homekit on.
Choose "Ciao".
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.
Persisting and restarting
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/
cd /home/pi/.firewalla/config/post_main.d/
nano start_homebridge.shand add this to start_homebridge.sh
#!/bin/bash
sudo systemctl start docker
sudo systemctl start docker-compose@homebridgenow docker and homebridge will automatically start when Firewalla reboots.
See https://help.firewalla.com/hc/en-us/articles/360054056754-Customized-Scripting- for more on running scripts at boot time.
To Check Docker Containers
sudo docker logs homebridgeThis 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
config.json:
Firewalla Gold
"accessories": [
{
"accessory": "LinuxTemperature",
"name": "Firewalla Core Temp",
"sensor_path": "/sys/class/thermal/thermal_zone0/temp",
"divisor": 1000
},
{
"accessory": "LinuxTemperature",
"name": "Firewalla Core 0 Temp",
"sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp2_input",
"divisor": 1000
},
{
"accessory": "LinuxTemperature",
"name": "Firewalla Core 1 Temp",
"sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp3_input",
"divisor": 1000
},
{
"accessory": "LinuxTemperature",
"name": "Firewalla Core 2 Temp",
"sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp4_input",
"divisor": 1000
},
{
"accessory": "LinuxTemperature",
"name": "Firewalla Core 3 Temp",
"sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp5_input",
"divisor": 1000
},
Firewalla Purple
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.
"sensor_path": "/sys/class/thermal/thermal_zone0/temp",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 |
/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 |
Updating Homebridge docker
cd /home/pi/.firewalla/run/docker/homebridge
sudo docker container stop homebridge && sudo docker container rm homebridge
sudo docker-compose up -d
sudo docker psImportant 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 pruneKnown Issue
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_netfilterafter 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.
References
- https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker
- https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold
- https://github.com/homebridge/homebridge/issues/1957
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.
Comments
83 comments
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
Michael,
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!
@cybermaster69 there's an uninstall at github.com/mbierman/homebridge-installer
That fixed it, thanks!
thanks, i would like to know if is possible to install home assistant and if there is a guide available. thanks
Home Assistant would be nice to install as I do not have a HomePod or Apple TV to act as the base station for HomeKit.
@Micheal
Worked, thanks
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!
@Michael Thanks. I tried that command you suggested and this is what I get:
Could it be a different problem that doesn't require reinstalling since the issue also happens with my other PiHole docker?
How do I update Node.js?
I have the following message, and I want to make sure I'm following the proper procedures:
@sergio,
You could do:
And see if it is running. However, unless you want to learn how to debug docker in general and this one specifically, the easiest thing to do is re-install it either using this guide or a script I wrote, github.com/mbierman/homebridge-installer
You may want to uninstall first just so nothing is left behind that might cause issues. There's an uninstall script in my installer as well.
Hello,
I'm having issues and I don't even know where to begin or what information to provide to help in troubleshooting.
I had homebridge running fine on my Firewalla. A few months ago, I noticed I could no longer use it or even login in the UI. I finally got around to ssh into the Firewalla. Everything is there without modification, but I can't not see the docker running. A similar issue is happening with my Pi-Hole (the only two dockers I have installed). Could it be something happenign with the Firewalla?
What can I do to troubleshoot why my dockers aren't running?
Hi Michael,
Thanks for reviewing. I’m miffed because I was able to get this working with a SmartThings hub when I had an Android phone but with the different ecosystem there’s no crossover compatibility and you need the Apple equivalent hub now. It makes sense it would still need a hub. I bit the bullet last night and bought a HomePod mini to be delivered this week. Thanks again!
Hey Mark,
Ah! So I haven't tried it, but I don't think homebridge alone is sufficient for that. Also, I don't think Bonjour does well over VPN. Apple expects any homekit environment to have at last one hub:
Understood, I was trying to do this without an official hub and direct connect to the firewalla that was hosting the homebridge, but it looks like it still communicates to the Apple app via mDNS/Bonjour or some method that isn't transferrable through VPN normally.
HomeKit doesn’t require VPN. Your hub will take care of this.
Hi Michael,
Thank you for responding. I have a garage door opener set up on HomeBridge and I wanted to add it to the Apple Home app in order to open and close it once logged in via VPN.
Hi Mark,
Not sure I follow your question. What are you trying to do exactly?
Hello,
Is it possible to add the HomeBridge to your Apple Home app via VPN? I have been messing around for a couple hours today with the firewalla having HomeBridge installed directly on it, VPNed to the firewalla, on paper I'd imagine this should be able to communicate since you're connecting directly to the server (originally I was trying to do it with HomeBridge hosted on my NAS and I was thinking the subnet difference was causing communication issues). However I can't for the life of me have it detect the HomeBridge hosted hub.
@Patrick,
🎉 🥂 Excellent! enjoy.
@Patrick, That would do it. Something is not set up correctly. The fastest thing would be to uninstall and install using a script that I wrote.
github.com/mbierman/homebridge-installer
I'm getting:
@Patrick can you try
In the homebridge terminal
@Michael, correct. 68.105.28.11 is my ISP DNS and the primary DNS server under my WAN configuration.
@Michael Bierman thank you for the reply.. sadly I have the same result.. did try your installer, and as before, the container spins up but internally fails, and starts to loop the "Re-installing homebridge..." errors. Seems something is broken with Node in the latest image.
Hello - I have everything working right now but, in regard to the homebridge-linux-temperature plugin, turns out the sensor path on my Firewalla Gold Pro is /sys/bus/platform/devices/coretemp.0/hwmon/hwmon4/... No idea why it's hwmon4 rather than hwmon1 like the guide suggests. Again, once I figured that out, everything is working but just curious why that is. Is that normal for Firewalla Gold Pro and is the guide maybe a tad dated? Thanks, Jarrod
What's the preferred way of keeping the homebridge components up to date? I realize I can log into homebridge and see whether the different components are up to date but I was wondering if there was an automated way to keep everything up to date.
@Sergio,
Try
@Michael - thanks for the suggestion, I went and checked a homebridge forum and they mentioned their problems when away in V1.8.X - it seems like mine Firewalla is running v1.6.1, so I need to try to update it. I'm going to do some digging thorugh here to see if I find the instructions to upgrade to the latest version and see if that resolves my problems.
@Sergio this seems like more of a homebridge question than firewalla. There are some great discussion groups. In this case, I'd suggest checking with the plugin owner/team.
Please sign in to leave a comment.