Recently I decided to upgrade my home wifi setup after hitting 50+ wireless devices. I upgraded from a Ubiquiti AmpliFi HD Mesh to using Ubiquiti's commercial line, Unifi.
Having more than 50 devices on a mesh network is not a great idea. Five of those devices are wireless HD video cameras that constantly stream to the cloud, which can quickly choke a wifi network and bring it to its knees. After doing some research I decided that building a Unifi setup in my house should be able to handle all of my devices. I went with the following:
- Unifi Security Gateway (USG) ($130)
- Unifi Switch 8 60W ($100)
- 2x Unifi nanoHD 802.11ac Wave 2 MU-MIMO AP (UAP-NANOHD-US) ($160 each)
Now, to set up and manage these devices, you have to run a piece of software called Unifi Controller. It's an app that can run on Windows, macOS, or Linux, and is the brain for the network. You adopt devices to be managed by the controller, set up your network, and then it sends out the configuration to all of the devices (provision). You can run the software when you need it, or you can keep it running to have it monitor your devices and keep track of network statistics, clients that connect to the network, network quality, etc. So it's better to keep it running all the time somewhere so it can watch the network and collect stats.
The Unifi Cloud Key Gen 2, an additional device you can get that runs the Unifi Controller, costs about $170. I decided to forego purchasing this device and decided I would run the controller on a Raspberry Pi 3B+ inside a Docker container for half the price of the Cloud Key Gen 2.
Good to Know
I recommend setting up the Unifi Controller on a Raspberry Pi first before you set it up on any other devices. If you do set it up on another device and adopt your Unifi devices into it you will have to migrate your Unifi site from that device to the Raspberry Pi, which takes a bit of extra work. If you are in this situation, follow the instructions below to get your new Unifi Controller running in Docker and then follow Ubiquiti's instructions on How to Migrate a Unifi Site.
To start, you'll want to get Raspian running on your Raspberry Pi. You can follow the instructions at RaspberryPi.org on how to do this. I set this up using Raspian Buster 4.19. I'll go through this, assuming you are using a fresh image of Raspian.
One other note before we get started is that you should have the Raspberry Pi physically plugged into your network. I wouldn't recommend running the Unifi Controller over wifi. If you happen to be provisioning an access point and it needs to reboot, and your Raspberry Pi is connected to that AP, you could run into some issues.
Open a terminal window on your Raspberry Pi and put in the following command to install Docker:
curl -sSL https://get.docker.com | sh
piuser permissions to run Docker commands:
sudo usermod -aG docker pi
Reboot your Raspberry Pi at this point.
sudo pip3 install docker-compose
Docker is installed.
Run Unifi Controller in Docker
Open a new terminal window and create a folder:
Go into the new folder so we can set up our docker container:
Make a new file called
docker-compose.ymlfor our container:
The last command should have you in
nano, a linux text editor. Paste in the following
version: '3.7' services: unifi: image: jacobalberty/unifi:arm32v7 container_name: "unifi" restart: always volumes: - ./data:/unifi ports: - 3478:3478/udp - 10001:10001/udp - 6789:6789/tcp - 8080:8080/tcp - 8880:8880/tcp - 8443:8443/tcp - 8843:8843/tcp environment: - TZ=America/Denver
This configuration will download and run the Raspberry Pi compatible version of the Unifi Controller. The Pi needs a special version because it has an ARM processor. It will automatically start this container again if the Raspberry Pi ever restarts. It creates a directory in our current directory called
datathat will contain all of the persistent data from the Unifi Controller so that we can back it up somewhere if you want to. Also, change the time zone at the bottom to match your timezone. You can find a list of TZ timezones here.
Press CTRL+O to save the file and then CTRL+X to exit back to the terminal.
Run the Docker container:
docker-compose up -d
You'll see a little bit of output in the terminal and see that
Check to make sure the
unificontainer is running:
docker container ls
You should see something like this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 6512ba16c6cf jacobalberty/unifi:arm32v7 "/usr/local/bin/dock…" 40 hours ago Up 40 hours (healthy) 0.0.0.0:6789->6789/tcp, 0.0.0.0:8080->8080/tcp, 0.0.0.0:8443->8443/tcp, 0.0.0.0:8843->8843/tcp, 0.0.0.0:3478->3478/udp, 0.0.0.0:10001->10001/udp, 0.0.0.0:8880->8880/tcp unifi
Get the IP address of the Raspberry Pi so you can get to the Unifi Controller from another system:
You should see something like this:
10.0.0.2 172.17.0.1 172.18.0.1 169.254.205.109
So, in my case, my Pi's IP address is
10.0.0.2. You should most definitely set the IP address of the Pi to be static. If the IP address of the Unifi Controller changes it will mess up your ability to adopt and provision devices on your network.
That's it! You did it! You are running the Unifi Controller on a Raspberri Pi in Docker. Now, to access the controller's web interface you can open a browser window on the Pi and go to
https://localhost:8443, or you can browse to it from another computer by going to (in my case)
To log into your Unifi Controller you will need to have a Ubiquiti Account.
I've had zero problems running the Unifi Controller on a Raspberry Pi 3B+. I did have some issues with my setup because I had set up my controller on a different machine, and I didn't understand that I had to migrate my site from my first device to the Pi. After I figured that out, I had zero issues. I think this is well worth the time and money. You can set this up for half the price of a Unifi Cloud Key Gen 2, though I am not sure how the Pi 3B+ would handle things in an enterprise environment, it's perfect for a home setup.