Guide: How to run UniFi Controller on the Firewalla Gold

Preface

• This is a technical doc for Pros. 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 in Router Mode only.
• Unifi Controller cannot be installed on Purple due to memory restriction.
• 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.

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

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

This command may need to be run every time the docker container is started.

Step 3: Add DNS entry for Unifi Controller

Run the following commands to map Gold's IP to Unifi controller in dnsmasq.

echo address=/unifi/172.16.1.2 > ~/.firewalla/config/dnsmasq_local/unifi

# Restart DNS Service
sudo systemctl restart firerouter_dns

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 dnsmasq config to the right domain.

Step 4: Access Unifi Controller from Gold managed network

Access the following URL and login to check for Devices in your network. If you have any trouble reaching the device try these links to access your Unifi Controller.

• https://172.16.1.2:8443/
• http://unifi:8080
• https://unifi:8443
  
  

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

And you are ready to go.

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