How To Setup A UniFi Controller On Raspberry Pi With Docker

Parts Used For Project

Why Raspberry Pi and Docker?

I recently decommissioned my 2 Dell R710s and replaced them with 10 PoE Powered Raspberry Pi 4 Model B (4GB) to save some money on electricity and use less air conditioning. Those 2 servers ran all of my virtual machines in my humble homelab.

Before decommissioning the servers, I had to build out an equivalent to run on a Raspberry Pi.

I had already been using Docker to run my Unifi controller so I knew exactly how I was going to handle the transition from VM to to Raspberry Pi.

I use the jacobalberty/unifi Docker image to run the controller. It’s worked great for me over the years. He keeps it updated regularly.

Something I knew but didn’t think about until I started building on the Raspberry Pi, was that I needed an image built for an Arm processor.

A quick check of the jacobalberty/unifi tags section on dockerhub showed that he had a build for arm32v7. Most of the Raspberry Pis today are ARMv8. The good news is that ARMv8 is backwards compatible with ARMv7. So that image should work just fine!

Getting Started

This tutorial is going to assume that you’ve already installed the most recent version of Raspbian onto your SD card and are able to SSH into your Pi.

I don’t have a tutorial for that. Maybe I’ll make one someday but there are probably already 37,382 of those tutorials on the internet. Just do a quick search and get that setup.

I will also assume you are running these commands as the pi user rather than root.

Update Raspbian

This first command will update the list of packages available to your Raspberry Pi. The second command will actually update the packages on your Raspberry Pi to the newest version of those packages.

sudo apt update -y
sudo apt upgrade -y

Install Docker

The next set of commands will download a script from docker.com, output it to a file named docker.sh and then run that script.

It’s always a smart idea to know what you are running on your servers. After running the curl command, you can (should) run cat docker.sh to view the contents of the script. This allows you to verify there is nothing malicious in the script that you are about to run.

This script basically just checks what Linux distribution you are running and downloads the proper versions of the Docker package for you. Feel free to check for yourself.

curl -fsSL https://get.docker.com -o docker.sh
sh docker.sh

Allow Pi User To Use Docker

This command will add the pi user to the docker group. We need to do this to allow the pi user to run docker commands.

sudo usermod -aG docker pi

Create A Directory To Store Data

Docker containers are (should be) ephemeral. This means they can be stopped, set on fire, started, destroyed and rebuilt without any issues.

For this reason, we don’t actually store data in the container. We are going to create a directory on the file system of the Raspberry Pi. Then we will mount that directory to the container when it runs.

Because memory cards can fail at anytime, it would be a good idea to backup this directory to an external hard drive using rsync or something similar. That will allow you to restore your setup without much effort. You can also use the built in backup utility within the UniFi Controller..

mkdir /home/pi/unifi/

Download And Run The Docker Image

This is the last step!

We tell the docker application to run the jacobalberty/unifi:arm32v7 image. If it can’t find the image on the system, it will download it automatically.

-d means to run in detached mode (in the background).

--restart=unless-stopped tells docker to restart the container if it breaks and stops for some reason.

--init will make the init process PID 1 inside the container.

-p is for mapping ports from the host to the container. Meaning -p 8080:8080 will allow you to hit port 8080 in the container through port 8080 on the host server.

-e will set an environment variable in the container. -e TZ='America/Phoenix' means to set the timezone to Phoenix. Here is a list of TZ names if you don’t already know yours.

-v is used for mounting volumes. We are mounting /home/pi/unifi on our host to /unifi in the container.

--name gives the container a friendly name that you can use to address and identify it by later on.

Here is the final command…

sudo docker run -d --restart=unless-stopped --init -p 8080:8080 -p 8443:8443 -p 3478:3478/udp -p 10001:10001/udp -e TZ='America/Phoenix' -v /home/pi/unifi:/unifi --name unifi jacobalberty/unifi:arm32v7

Connect To The UniFi Controller

If you’ve done everything correctly, you should be able to go to https://<IP address of your Raspberry Pi>:8443 and start setting up your UniFi Controller!

You may have to wait a minute before the web GUI is up while the docker container is starting up.

Basic Docker Commands

You can check the status of all running containers by running docker ps on the Raspberry Pi.

pi@unifi-pi-01:~ $ docker ps
CONTAINER ID        IMAGE                        COMMAND                  CREATED             STATUS                PORTS                                                                                                                            NAMES
dff5e76b71e7        jacobalberty/unifi:arm32v7   "/usr/local/bin/dock…"   10 days ago         Up 5 days (healthy)   0.0.0.0:8080->8080/tcp, 6789/tcp, 8843/tcp, 0.0.0.0:3478->3478/udp, 0.0.0.0:10001->10001/udp, 8880/tcp, 0.0.0.0:8443->8443/tcp   unifi
pi@unifi-pi-01:~ $

Look for the STATUS field in the output. It will tell you if the container is healthy, starting or if something has gone wrong.

docker stop unifi will stop the container.

docker start unifi will start the container.

docker exec -it unifi bash will give you a bash shell inside the container so you can poke around.

pi@unifi-pi-01:~ $ docker exec -it unifi bash
root@dff5e76b71e7:/unifi#

Checkout docker docs for more learning materials specific to Docker.

I’m Super Lazy…

If you are too lazy to read through all of that and just want a UniFi controller up and running on your Raspberry Pi, I made a script specifically for you.

Run these commands and you should be good to go!

git clone git@github.com:tynick/unipi_install.git
cd unipi_install
./install_unifi.sh

That’s about all there is to it.

Subscribe to my mailing list below to be notified when I make a new post or follow me on Twitter. Either would be really appreciated.

Twitter is best if you have any questions.