As an Amazon Associate I earn from qualifying purchases. Purchasing through my Amazon links helps me keep the site up and running.
How To Setup A UniFi Controller On Raspberry Pi With Docker
Parts Used For Project
|Raspberry Pi||I am using a Raspberry Pi 4 4GB to run my UniFi controller but it’s definitely not needed. You can absolutely get by with a Raspberry Pi 3 B+. The Raspberry Pi 4 is still sort of hard to come by and you might already have a Raspberry Pi 3 B+ sitting in your desk drawer.||https://amzn.to/2PZezat|
|Micro SD Card||I have been using the Samsung MicroSDHC EVO Select cards for a while. I havent had an issue yet. All of my Raspberry Pis are using either a 32GB or 64GB. They are great for the price.||https://amzn.to/2Q85FXY|
|Power Supply||All of my Raspberry Pis are using a Raspberry Pi PoE HAT but that isn’t a requirement. You just need a power supply that puts out a good amount of power(at least 2.5A). This one puts out 3A and has an on off switch built in. Make sure you select the Raspberry Pi version you are using. All Raspberry Pis use Micro USB except the Raspberry Pi 4, which uses USB Type C.||https://amzn.to/2ZHBPy9|
|Ubiquiti Unifi Security Gateway (USG)||My homelab uses a Unifi Security Gateway Pro but both require a UniFi controller to configure these items.||https://amzn.to/2HUMRFj|
|Ubiquiti Unifi 802.11ac Pro (UAP-AC-PRO)||I have one of these inside my house and another mounted on the ceiling of my back patio. I don’t have a single dead zone on my property. These are really great access points. They can be powered via PoE if you a PoE switch.||https://amzn.to/2A0IFzl|
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!
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
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
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..
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 firstname.lastname@example.org: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.