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.
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 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. 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/and add this to start_homebridge.sh
cd /home/pi/.firewalla/config/post_main.d/
nano start_homebridge.sh
#!/bin/bash
sudo systemctl start docker sudo systemctl start docker-compose@homebridge
now 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 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
Known 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
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.
Great guide! I have got it all working … almost! I am trying to workout why is that a plug-in I am trying to use is being denied opening a UDP socket (and thus fails). Any suggestions @firewalla? Are there particular restrictions that might cause this? (I am on firewalla gold)
@sk0rp10 what plugin?
Michael, it’s Nest SDM
@sk0rp10 ah. I have other nest stuff, but not their cameras so I don't know how I can really test this.
The plugin doesn't really matter, @Michael, the issue is generically described here, which was opened for a different one: https://github.com/Sunoo/homebridge-camera-ffmpeg/issues/1087
@sk0rp10 nothing shows in that github issue.
I install ffmpeg in my homebridge startup.sh script if that's of any help.
Okay, basically it’s an issue with the get-port api. It’s discussed in the thread I linked . Nothing to do with ffmpeg either
@Michael if it helps, here's the GitHub Issue where we're discussing this problem with the author of the Nest SDM plugin: https://github.com/potmat/homebridge-google-nest-sdm/issues/31
Thanks for the tutorial! Super easy to follow. Homebridge is running on my FWG and I'm able to access the Homebridge UI. However, it looks like there's some DNS issue blocking Homebridge from accessing the npm registry, making it so I can't install plugins.
I'm getting this error in the Homebridge logs:
Do you know if this this caused my FWG config or something else?
@patrick can you try the following from the device running homebridge?
@Michael, those seem to be working. Response for dig:
Response for ping:
@Patrick
@Michael, steps 1-3 done, but my ipinfo is not showing 68.105.28.11.
@Patrick, Is 68.105.28.11 your ISP DNS?
@Michael, correct. 68.105.28.11 is my ISP DNS and the primary DNS server under my WAN configuration.
@Patrick can you try
In the homebridge terminal
I'm getting:
@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
That fixed it, thanks!
@Patrick,
🎉 🥂 Excellent! enjoy.
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.
Hi Mark,
Not sure I follow your question. What are you trying to do exactly?
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.
HomeKit doesn’t require VPN. Your hub will take care of this.
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.
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:
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!
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?
@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.
Please sign in to leave a comment.