Guide: How to run UniFi Controller on the Firewalla Gold Series Boxes

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:

1. A network as your docker network, we will use 172.16.1.0/24 in this tutorial.
2. 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/unifi

Note 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 5003

This 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

cd  /home/pi/.firewalla/run/docker/unifi/
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.sh

And run the script:

/home/pi/.firewalla/config/post_main.d/start_unifi.sh

Which will restart docker And 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 prune

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