How to install a unifi controller on your raspberry pi

Installing a unifi controller for fun and profit

as an alternative to buying an expensive unifi cloud key or running a unifi controller as a windows service on a non-dedicated machine, I found the idea of using a raspberry pi to be very appealing. This is my guide to set it up. I have two goals with this article: to give the raw steps and instructions to complete the task, and also to explain the process flow to help someone understand the why behind the what.

There are many ways to set this up; I have tried several, but found this to be the cleanest and most straightforward. Most recently I tried unfipi, which kept giving me “certificate revoked” errors when i tried to log into the dashboard. Further, this installation was overly complicated with the use of webmin as a management tool. This method seemed easy to set up, since it was simply a matter of writing an image file to the sd card with Belena Etcher. In the end, it was not worth it, and the certificate errors were a dealbreaker for me.

most of the other methods involve some form of docker images; i have seen docker, portainer, and others. The problem with this is, there are so many different images from so many different sources and people that you never know which to trust, or what the settings and configuration is. It’s just not worth looking through them all and trying to compare and understand which would be best, when I can easily set up a clean install from a source I trust.

Hardware requirements for this guide will be: A raspberry pi (i am using a pi 4 2gb), an sd card, and an ethernet cable connected to your router or switch. of course we will need another PC to setup the sd card boot drive for the pi.

so, for this guide, here is an outline:

  1. install OS
  2. set up SSH
  3. boot and connect remotely to Pi
  4. update os
  5. install java
  6. install and configure rng tools
  7. install the unifi controller software
    • add unifi repo to apt-get
    • install controller
  8. run controller software
  9. migrate old controller site to new controller
  10. profit

Steps 1-3 are setup, then 4-6 are installing prerequisites for the controller. step 7 is the actual insteall, and then 8 and beyond is config and setup of the controller itself.

step 1: install OS on SD card

to do this, you’ll need to download the latest version of rasberry pi OS (rasbian). go here and download: Raspberry Pi OS (32-bit) Lite – Minimal image based on Debian Buster. Extract this file.

download Belena Etcher. Install and run it. insert SD card. Within etcher, select the image we extracted as the source, and select the sd card as the target. start data write.

step 2: set up SSH

When complete, remove and then re-insert SD card. browse to the root directory, using terminal, and create a new file called “ssh”. make sure not to give this filename any extension. This can be done in a posix-compatible terminal by running:

touch ssh

or, in windows, browse to file explorer. right click, select new -> text document. rename it as “ssh” and be sure to delete the the .txt extension. Windows may ask to confirm changing the extension; select yes.

At this point you can remove the sd card from your pc and insert it into the raspberry pi.

step 3: boot and connect

connect raspberry pi to power and network. boot up pi.

check your router to determine the IP address of the new device.

using a SSH client of your choice (putty on windows or terminal on mac/linux), log into the pi by running the following in a terminal:

ssh pi@192.168.x.x

change the ip address above to match your device found in your router. When asked for password, type in the default “raspberry”.

the command prompt should change, and we are now connected to the raspberry pi.

step 4: update os

we want to make sure we are running the latest version of everything to ensure the best performance and compatibility. to do this, we need to run two commands. the first will update the list of packages which have new versions available. The second command will actually execute the upgrade of these packages to the new version.

first, we run:

sudo apt update

and after:

sudo apt upgrade

step 5: install java

This is a simple command, but was difficult to determine the correct version of java. as of now, unifi uses java 8, and we want the openJDK.

step 6: install and configure rng tools

step 7: install the unifi controller software

step 8: run controller software

step 9: profit!

some guides will tell you to flush the MongoDB cache, and a few other steps can be added in.

documentation/additional references

2 responses to “How to install a unifi controller on your raspberry pi”

Leave a Reply

Your email address will not be published. Required fields are marked *