Running Ubiquiti's Unifi Controller in Docker on a Raspberry Pi

A simple process that is well worth your time if you are using Unifi products.

Posted by Dion Munk on May 04, 2020

Running Ubiquiti's Unifi Controller in Docker on a Raspberry Pi

UPDATE: I have a video tutorial of the complete process for setting up Unifi on a Raspberry Pi using Docker.

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.

My Network

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.

Setup

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.

Install Docker

Open a terminal window on your Raspberry Pi and put in the following command to install Docker:
```
curl -sSL https://get.docker.com | sh
```
Give the pi user permissions to run Docker commands:
```
sudo usermod -aG docker pi
```
Reboot your Raspberry Pi at this point.
Install docker-compose:
```
sudo pip3 install docker-compose
```
Docker is installed.

Run Unifi Controller in Docker

Open a new terminal window and create a folder:
```
mkdir unifi
```
Go into the new folder so we can set up our docker container:
```
cd unifi
```
Make a new file called docker-compose.yml for our container:
```
nano docker-compose.yml
```
The last command should have you in nano, a linux text editor. Paste in the following docker-compose.yml configuration:
```
version: '3.7'
services:
  unifi:
    image: jacobalberty/unifi:latest
    container_name: "unifi"
    restart: always
    volumes:
      - ./data:/unifi
    ports:
      - 3478:3478/udp
      - 6789:6789/tcp
      - 8080:8080/tcp
      - 8443:8443/tcp
      - 8843:8843/tcp
      - 8880:8880/tcp
      - 10001:10001/udp
    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 data that 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 unifi is starting.

Check to make sure the unifi container 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:
```
hostname -I
```
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) https://10.0.0.2:8443.

To log into your Unifi Controller you will need to have a Ubiquiti Account.

Conclusion

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.