Install the UniFi Controller Application on a Raspberry Pi with Docker

Those who use or own Ubiquiti UniFi products mostly are familiar with the UniFi Controller. It is software used to manage all of your UniFi gear in a single, beautiful web-based dashboard. Ubiquiti sells their UniFi Cloud Key (affiliate link) if you wish to have a dedicated device, but you can also install it on your own hardware such as a Raspberry Pi (affiliate link) . You can save a little bit of money by using a Raspberry Pi (around $50-60 versus $90-100 depending on the accessories purchased for the RPi), and you also have the flexibility to run additional software on the same device. I run a secondary Pi-hole DNS server on the same Raspberry Pi that has the UniFi Controller installed. However, I would recommend you only use light weight apps since the UniFi Controller is a heavy weight application for the RPi – at least with memory usage. Pi-hole is one such light weight application that will not interfere with the performance of the UniFi Controller, which runs quite nicely for home network purposes (I cannot vouch for the performance of a larger scale network).

I originally installed the UniFi Controller directly on the Raspberry Pi by installing Java and then the UniFi Controller software. This worked beautifully for several months. Starting with version 5.10.17, the UniFi Controller software would no longer start properly. I tried doing some basic troubleshooting and reinstalling the software. Nothing seemed to work. So I thought I would look into a Docker version of the UniFi Controller since I already have Pi-hole installed on Docker on the same RPi. Quickly, I discovered that there is no official Docker version of the UniFi Controller. That is often a bummer when you want to use containers since it is nice to have official support (if it is well maintained). Sometimes you have to rely on community versions and hope they keep the images up to date. I tried one Docker image but it did not seem to work. However, I do not know if it was designed to work for the ARM architecture of the RPi. The Docker image I used is ryansch/docker-unifi-rpi especially since it the image is designed to work for the Raspberry Pi. There is also the linuxserver/unifi-controller image which may also work for you.

Install Docker and Docker Compose

To install the UniFi Controller on Docker, let us install Docker if you have not already done so:

curl -sSL https://get.docker.com | sh

Then you can add the default Raspberry Pi user “pi” to the “docker” group if you wish to run docker without running the command with “sudo”:

sudo gpasswd -a pi docker

You will need to log out and back in or reboot your Raspberry Pi in order for the group change to occur.

Docker Compose can be installed with the following commands:

sudo apt install python-pip
sudo pip install docker-compose

Download the UniFi Controller Docker Image

Now that you have the Docker software installed, you will need to a create a directory to place the Docker Compose file for the UniFi Controller. Data may be stored in that folder as well.

To install the UniFi Controller Docker image, run the following commands from your home folder:

mkdir unifi && cd unifi
curl -O https://raw.githubusercontent.com/ryansch/docker-unifi-rpi/master/docker-compose.yml
sudo docker-compose up -d

You may edit the docker-compose.yml to point to a different tag before running the last command if you do not want the latest UniFi version.

Note that this image runs the UniFi Controller in the “host” network mode which means the ports needed by the UniFi Controller are mapped directly to the host devices as though it is running natively on the host. You do not need to map any ports to the host device like you typically do with many Docker images. Some people may not prefer to run in host mode, but I think for the UniFi Controller it makes sense.

One of the images I was looking at said that Layer 2 adoption of UniFi devices may not work unless the image is set to “host” mode and that you would have to do Layer 3 adoption, which means logging into your device via SSH to tell the device the IP address/port of your UniFi Controller. That is cumbersome to me as I rather have the UniFi Controller software find all of my devices on my network automatically without the extra trouble. Granted I do not have many UniFi devices, but I like the “it just works” functionality.

Log into the UniFi Controller

Now you may try logging into the UniFi Controller page by going to the address of your Raspberry Pi. Something like https://192.168.1.5:8443. Remember the HTTPS port for the UniFi Controller is 8443 by default.

You should see the page that walks you through the first steps to setting up your UniFi Controller. If you have saved a backup of the configuration (and I highly recommend that you do so), you can import the backup file. This will get you up and running very quickly.

I try to make periodic backups so that I can pick up where I left off in case I have to move the UniFi Controller to a new devices or have to reinstall software. You will not regret making a backup! I have used my backup file several times when I moved my UniFi Controller from my PC to a Raspberry Pi, when I reinstalled my Raspbian OS after I messed up the network settings so badly that I could not easily fix it, and when I moved to using a Docker image on my Raspberry Pi. It makes for a pretty seamless transition.

Auto Update the UniFi Controller Docker Image

If you wish to have your Docker image for the UniFi Controller updated to the latest release automatically, you may use another Docker image called Watchtower. To install Watchtower use the following command:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  v2tec/watchtower:armhf-latest

You should now be up and running and have automatic updates setup! Note that you will still need to update your devices firmware through the UniFi Controller software web portal. This automatic update is only for the UniFi Controller software. It saves you from having to pull new images every time there is a new update, which is nice since you do not always have to track when the latest and greatest changes are released. Assuming you do not have other heavy software running on the Raspberry Pi and you do not have a large number of UniFi devices (which may have an impact on the system load), the RPi should provide good performance for a lower cost than the UniFi Cloud Key.