Preface
- This is a technical doc for advanced users. The purpose is to get the UniFi controller running. Refer to UniFI documentation about adopting devices and other configuration issues.
- This is for Firewalla Gold series boxes in Router Mode only.
- Installing Unifi Controller on Firewalla Purple series and Firewalla Orange boxes is not recommended due to memory limitations. You can use Unifi switches and APs with Purple series and Orange boxes. If you have a Firewalla Purple or Orange box, just run the controller somewhere else. This can be a computer, Raspberry Pi, NAS, etc.
- Incorrect settings of port forwarding will result in ports being opened on your WAN interface.
See Important Note: Preserve Resources below.
Step 1: Install Unifi Controller docker image
You have to choose:
- A network as your docker network, we will use 172.16.1.0/24 in this tutorial.
- A static IP for your unifi controller instance, we will use 172.16.1.2 in this tutorial.
Use the values recommended in this guide unless you know what you are doing and need to change these.
1. Create folder /data/unifi. This is where your docker container will reside.
sudo mkdir /data/unifiNote that unifi takes nearly 800Mb of disk space in the current controller release.
2. Create the file, /home/pi/.firewalla/run/docker/unifi/docker-compose.yaml.
# make unifi storage directory
mkdir /home/pi/.firewalla/run/docker/unifi/
# change directory
cd /home/pi/.firewalla/run/docker/unifi/
# edit with your favorite editor
vi /home/pi/.firewalla/run/docker/unifi/docker-compose.yaml
Add the following to docker-compose.yaml
version: "3"
services:
unifi:
container_name: unifi
image: jacobalberty/unifi:latest
volumes:
- '/data/unifi/:/unifi'
environment:
JVM_MAX_HEAP_SIZE: '512M'
restart: unless-stopped
networks:
default:
# static IP address for unifi controller
ipv4_address: 172.16.1.2
networks:
default:
driver: bridge
ipam:
config:
# your chosen docker network here
- subnet: 172.16.1.0/24
For detail, please refer to Unifi Controller docker image guide at https://hub.docker.com/r/jacobalberty/unifi
Also, once you have your YAML file, be sure to validate it with a service like https://www.yamllint.com/. It is very easy to have a small error that causes things to fail.
Note: You may choose your favorite docker image for Unifi Controller or build your own. The overall steps are the same.
3. Start the Unifi docker container.
sudo systemctl start docker-compose@unifi
Step 2: Add routing rule for docker network
Run the following commands:
sudo ip route add 172.16.1.0/24 dev br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') table lan_routable
sudo ip route add 172.16.1.0/24 dev br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') table wan_routable
sudo ip -4 rule add from all iif br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') lookup lan_routable priority 5003This command may need to be run every time the docker container is started.
If you are using Gold SE, run one more command to add SNAT for the docker network.
sudo iptables -t nat -A POSTROUTING -s 172.16.1.0/16 -o eth0 -j MASQUERADE
Step 3: Add DNS entry for Unifi Controller
Use Firewalla's Custom DNS rules to create a DNS record for "unifi" to 172.16.1.2 and then access the controller at https://unifi:8443 See the Custom DNS rule tutorial.
Note: The default inform URL for Unifi devices is http://unifi:8080. This is the reason why the above entry needs to be added to the dnsmasq configuration so that Unifi devices will inform the unifi controller in docker via this URL. If the inform URL is changed on devices, you may need to set the inform URL back or update the Custom DNS rule to the right domain.
Step 4: Access Unifi Controller from Gold managed network
To access the controller, try https://172.16.1.2:8443/ and login to check for Devices in your network.
You can make it easier to remember how to access the controller using Firewalla's Custom DNS rules. For example, you may create a DNS record for "unifi" to 172.16.1.2 and then access the controller at https://unifi:8443 See the Custom DNS rule tutorial.
You should be able to "adopt" UniFi devices as needed and then see all your devices in both Firewalla and the UniFi Controller.
Step 5: Persisting The Configurations
You must be on firewalla 1.971 or later for this
- If you have installed UniFi controller before 1.971, please change your docker-compose.yaml file accordingly and run the following commands
sudo docker-compose down
create folder /home/pi/.firewalla/config/post_main.d and the following file
/home/pi/.firewalla/config/post_main.d/start_unifi.sh
#!/bin/bash
sudo systemctl start docker
sudo systemctl start docker-compose@unifi
sudo ipset create -! docker_lan_routable_net_set hash:net
sudo ipset add -! docker_lan_routable_net_set 172.16.1.0/24
sudo ipset create -! docker_wan_routable_net_set hash:net
sudo ipset add -! docker_wan_routable_net_set 172.16.1.0/24
now change the permissions
chmod a+x /home/pi/.firewalla/config/post_main.d/start_unifi.shAnd you are ready to go.
If the docker service doesn't start, please follow this guide to reset your docker service. https://help.firewalla.com/hc/en-us/articles/360060535553
Updating the Unifi Network Application (Controller)
If you need to update the Unifi Network Application you can use these commands after using ssh to access your Firewalla.
cd /home/pi/.firewalla/run/docker/unifi
sudo docker pull jacobalberty/unifi:latest
sudo docker container stop unifi && sudo docker container rm unifi
sudo docker-compose up -d
sudo docker ps
sudo docker system pruneImportant 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. UniFi Controller is a large docker image. 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.
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
144 comments
https://github.com/mbierman/unifi-installer-for-Firewalla
This worked for me nicely. I am not responsible for anything by offering this information.
So I got this figured out today and Unifi Controller is up and running. Here's what I didn't know and the guide didn't make entirely clear. Probably bc this guide is for Pros, which I am not.
After step 1 you need to run the following command: docker-compose up -d
Once the compose file is executed and the container is pulled you can move onto Step 2.
I misinterpreted step 3 as needing to manually create a file containing those 2 commands and place it into a directory. What it really means is just run those 2 commands making sure you replace the GOLD_LAN_IP with your Gold's IP address. Once I did that I was able to get to the Controller setup wizard.
The last hurdle is that I wasn't able to use my Ubiquiti account to create the Site in this controller, so what you have to do is to create a local account. I can't remember what you click to do that, but it's not hard to find.
Now, that I did all of that I was able to get into the controller and my switches were there and adoptable.
If you are a complete n00b like me hopefully this helps.
Thanks, Blake!
I would say step 3 is not a typical way for documentation to show that those are shell commands, so I made many of the same assumptions you did. Something like this might be better.
# Restart DNS Service
Now I have the unifi controller running on FWGold! I'm thinking I may hold off migrating from the controller I have on my Synology to allow FW to harden the release a bit more. But it is great to know I can consolidate if I want to.
@Blake
Updated the doc that you don't have to run command docker-compose up -d, sudo systemctl start docker-compose@unifi will do everything.
@Michael
Updated the doc!
@Blake Try sudo docker network rm unifi_default and then sudo docker-compose up -d
If not working, sudo docker-compose down and start over again.
That worked! So I ran the first command, then moved to the docker unifi directory and ran the second command. Then I completed step 2 and 3 of the guide again and I can finally get to the controller. I had to setup a new local admin account and couldn't use my UI account but I'm in. Thanks.
Been using this for weeks now, love it !!
If you guys have some time, could you give a shot at "home assistant" ?
Docker install is easy but networking...
Installation on Docker - Home Assistant (home-assistant.io)
@nicolas, Having tried both, I prefer homebridge to home assistant. Here's a guide https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold
Has anyone tried updating their controller or updating any of the devices? I can't seem to do any firmware updates from the container.
how do you update the container? A link to instructions would suffice.
https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold#updating-homebridge
Thanks @Michael. That did the trick.
You bet @Blake! Glad you are in business.
I've got this working just fine. One question though.
While testing my Guest network I realised I was able to load Unifi and Pihole - but that network has a block on all local LAN traffic. For instance I am unable to route to a server on the LAN.
I am guessing this must be because in step 2 and 4 we're making the subnet WAN routable? How do I un-do that? I don't really understand why we're using different commands in 2 and 4 (`sudo ip route` vs. `sudo ipset create`).
So if I wanted to change my controller to a different subnet for the purposes of using a management vlan different than my main lan, would it be faster to just start from scratch or should I update my Config with the new subnet?
Specifically I set this up on 192.168.30.1 and now would like to move my controller over to 192.168.20.1 so I can have my Unifi gear on a different network than my main lan.
Have you tried resetting them to factory?
@Blake.. no, I have not.. Edit: I just did.. thought the issue laid else where... but that did it. Thanks for the help!
@Abbass did you create the directory first?
@Stephen I don’t have a video, but I created a script that does pretty much everything for you. /github.com/mbierman/unifi-installer-for-Firewalla
@michael, that made it way too easy. Thank you
Hey Josiah - quick one - have you added the DNS rule for "unifi"? Wondering if the switch can't find the "host".
Sounds like an issue with the device finding the controller.
Note: You can now do this directly in DNS Service > Custom DNS rules - create a rule to resolve 'unifi' to your docker containers IP.
Interesting! One of the problems I found running Unifi in docker on the Firewalla itself was the lack of visibility of the "flows" and ports. I also found that it opened ports on the Firewalla outside so I since moved it onto my Raspberry Pi (and just let my Firewalla be a Firewalla).
Since doing this I've been able to follow Unifi's guide for needed ports / mixed with flows I've seen the devices make: https://help.ui.com/hc/en-us/articles/218506997-UniFi-Network-Required-Ports-Reference - I wonder if there's a restriction here you don't have visibility of. To be more specific I've allowed the following ports inbound to my RPI running Unifi on Docker from the network my unifi devices live on: 3478, 5514, 6789, 8080, 8443, 8843, 8880,1000. You should enable these in the docker compose file. On that note it's worth restarting the container also while you're there (sudo docker-compose down && docker-compose up -d)
The other thing I'd try doing is Rebooting the Firewalla. This should re-apply the route tables you "persist" in the instructions above as the devices typically need internet connectivity to adopt and perhaps your docker container isn't "wan" routable.
Try factory resetting the switch. I’ve had to do that before when the adoption failed.
Don't assume cloud key is the solution. I recently had a UNVR which I couldn't register with Unifi Cloud although pretty much everything else worked. I reset it and tried multiple things but nothing helped. I assumed it had something to do with not having a proper hosted Unifi OS (but rather installed in a container on Firewalla). However I contacted support and they RMA'd the unit saying something was wrong with it. I was doubtful but the replacement arrived and worked without a hitch. I think they must use some type of cryptographic chip to prevent emulating their hardware and that chip fails sometimes.
I trust the jacobalberty distro. Yes, there is a little lag between when unifi releases something and when it gets into this docker image. But at the same time, it has been very stable. I think they are careful about pushing out the distro Personally I value stability more than living on the edge in this case.
@Pat, You should update the container as a whole. People who build the dockers do a lot testing about the configuration and generally, should be trusted. To update the container, Fiewalla has included instructions.
https://help.firewalla.com/hc/en-us/articles/360053441074-Guide-How-to-run-UniFi-Controller-on-the-Firewalla-Gold-Series-Boxes#h_01HN3THHC2XV0EZWHQZYHH66QD
Thank you @Michael for the link. Will definitely look into that today.
+1 https://github.com/mbierman/unifi-installer-for-Firewalla this has consolidated all the required steps including docker prune as well at the end. mine is 8.1.113 now. Additionally I've created a unifi account and added the firewalla hosted unifi controller to the site manager. with that I could manage the configurations at https://unifi.ui.com/ instead of https://172.16.1.2:8443, I could manage most of the configurations via the iOS App Unifi.
I've automated the updates via a new cron (monthly). I've commented the user input to continue in the updatedocker.sh.
I've tried the how-to, and I've run the script. Neither seems to be working for me.
When running the how-to, I can never navigate to the host at 172.16.1.2. I can see the container running but still can't navigate to it via another host on the network.
I reset the FWG to factory settings and tried running the script. It launches the host but repeatedly writes "RTNETLINK answers: File exists" on my screen when trying to configure networks.
Given the deprecation of the Unifi-Controller, I have compiled a comprehensive guide outlining the installation process of the Unified Network Application (UNA) on the Firewalla Gold firewall. Although I do not possess a Purple firewall, I have identified the new database requirements and believe that the Purple firewall does not support UNA.
https://github.com/TheeNawMan/firewalla-docker-scripts/tree/main/unifi-network-application
For those new, with [ existing / old Unifi AP ]
Best combo currently, i can recommend to ANY layman starting or moving to firewalla
1) Get Gold SE
2) get any u6 or even. better u7p
3) Setup the Gold SE,
4) Use Michael Bierman's AMAZING script, it LITERALLY cuts down the time by 3/4 of this thread.
5) Give it 10mins [ warn your family , 20mins tops ]
6) configure the. controller
7) use https://www.anythingyouwant.com
reboot, and run your ssh optimization tcp connection, and you're literally, pun intended [ Gold ]
Docker + Unifi controller + all the brillant folks
And p.s skip the purple for controller, the ram will die first before anything else......
@Michael Bierman thanks alot for that script./... !
as of 8jan2025 SG
Please sign in to leave a comment.