How to Install and Configure UniFi Controller on Raspberry Pi?

I’ve managed access points for years as a sysadmin, and once you have 10+ devices connected, it can quickly become a nightmare. UniFi solved that problem for us, but its dedicated gateways can be expensive. The good news is that a Raspberry Pi can handle the controller role instead. Here’s how to set it up.

The UniFi Network Application can be installed on Raspberry Pi by adding a Debian repository and using apt to install the required packages. A .deb package is also available directly on the website. Configuration can then be done via a convenient web interface.

The installation itself is straightforward. You can install it like any Debian package. But the access points configuration is not so easy, and I saw no article explaining this. As I’m using it at work, I can show you all the configuration steps with real access points and clients. Let’s see how to do this!

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

Ubiquiti Networks Products

Ubiquiti Networks Introduction

Ubiquiti Networks is an American company, selling hardware for wireless technologies like access points, routers and cameras.

They started with wireless devices, and they are now diversifying upon a broader range of products. The latest innovative product concerns solar technology that helps you to manage solar farms.

Anyway, the product that interests us today is their popular UniFi line of wireless network devices. These will be controlled by a software: UniFi Network Application (which used to be known as the UniFi Controller in the past).

The goal of the Unifi Network Application is to manage multiple access points and wireless devices from a single web interface. From there, you can see all the access points and broadcast a unique SSID. The controller will handle the roaming between access points and load distribution.

Why Do I Need These Products?

These products target mainly companies and large areas but you can have the same “prosumer” needs at home if you have issues with your Wi-Fi connection (rooms with no network, roaming, stability, etc.).

Before switching to Ubiquiti products, I remember having tested many brands to solve my issues, but none of them could support over 10-20 users simultaneously (I even tested a fireproof model from D-Link, something like this one on Amazon ^^). So, I definitely recommend trying Ubiquiti, as it’s inexpensive compared to enterprise brands but performs very well.

For example, let’s say you need three access points at home. If you turn your Raspberry Pi into a Unifi controller, you will only have one Wi-Fi SSID (outdoor included)—instead of three. And you can move from one side to another without disconnection.

Ubiquiti Products

Ubiquiti products are distributed by resellers but are also available on several e-commerce sites:

To test these products, you don’t need many things. Just buy one or more access points and build your professional wireless network.
Here is the link: Ubiquiti UniFi AP on Amazon.

You have several packages available: Only one, 2 AP (access point), 4 AP, etc.
Choose the one you prefer, but there aren’t big savings for buying bulk, so you can start with one or two, and order the others after.

https://www.youtube.com/watch?v=1UrWfFWYBAQ

If you have a PoE Switch (like this one on Amazon), you can plug them only to the network cable. An Ubiquiti switch is not mandatory, this one from Cisco is cheaper for example. It depends on what you want to do with it and how many APs you have.

Whatever your choice, a PoE switch will make the installation easier.
If you want to start without it, there’s another option: Ubiquiti provides an adapter with the AP (power cord + network = PoE Network), but you need a power outlet and two RJ45 cables instead of only one cable for everything.

Here is the link to the PoE injector on Amazon, make sure to check the AP power requirements are they are not all the same (a Pro AP needs PoE-48 for example).

UniFi Network Application Installation

Now that you understand what UniFi products are, we can move on to setting up the software. Here’s an overview of how to turn your Raspberry Pi into a UniFi controller:

• Install and update Raspberry Pi OS.
• Set a static IP address.
• Download the Unifi Network Application autoinstaller script.
• Run the UniFi autoinstaller script.

Don’t worry, I’ll explain everything in detail next.

Installation on Raspberry Pi OS

As for any tutorial on this site, you first need to install Raspberry Pi OS on your Raspberry Pi.
Any version will do (I’m using Raspberry Pi OS Lite).
If you don’t know how to do this, read my article on How to install Raspberry Pi OS on your Raspberry Pi.

Once installed, update your system and reboot:
sudo apt update
sudo apt upgrade
sudo reboot

And enable SSH access with:
sudo systemctl start ssh
This way you can follow this tutorial from your computer (if needed, check this post to learn more about this).

Tip: Command lines can be a pain to memorize. I put the essential Linux commands on a printable cheat sheet so you don't have to keep googling them. You can grab the PDF here if you want to save some time.

Set a Static IP Address

As our Raspberry Pi will act as a server on our network, we need to use:

• A wired connection
  If you want a fast Wi-Fi network, you need to have your controller and your access point on a good connection. So, I don’t recommend setting up the controller with a Wi-Fi connection.
  Check this tutorial if you need help with this step: How to Connect the Raspberry Pi’s Ethernet Port (2 ways).
  
• A static IP address
  The Raspberry Pi will become an important node on your network, so we need to fix its IP.
  By default, the Raspberry Pi uses DHCP to get a random IP among those available.

You can either set a static IP in the DHCP server (on your router probably) or do so from the Raspberry Pi configuration. If you don’t know how to do this, I already explain it at the end of this article. Feel free to take a look before going further: Set a static IP address on your Raspberry Pi.

UniFi Network Application Installation

Now that your Pi has a static IP, we’re ready to start the installation.

Note: Unifi Network Application requires dependencies that often conflict on Raspberry Pi. Workarounds have gotten messy, so to make things easier, we’re going to use an automated installer script.

This script is provided by GlennR, who has maintained it for the last eight years.

Here’s how to install UniFi Network Application on Raspberry Pi:

• Find the most recent script available on GlennR’s page: here.
  The script detects your Linux distro and even works on Raspberry Pi OS.
  
• Copy the link for the newest version and download it using wget:
  wget https://get.glennr.nl/unifi/install/unifi-10.5.67.sh
• Run the script using the filename you downloaded:
  sudo bash unifi-10.5.67.sh
• The script will initiate and a splash screen will appear.
  The script will detect your Raspberry Pi (and use special steps for its hardware).
  It will begin by installing a few prerequisite packages.
• You’ll then be asked a few setup questions:
  • Do you want to automatically upload the support files? N
  • Do you want to keep the script on your system? Y
  • Which software do you want to install? 2 (UniFi Network Application)
  • Would you like to use compiled MongoDB? Y
    
  • Do you want to proceed with updating your system? Y
• Then comes the most important part: the script will begin installing dependencies (mainly MongoDB and Java) that will be compatible with your system.
• Finally, the Unifi Network Application is installed.
  At the end, it provides the link you will use to access the admin portal in your browser.
  

Now that the installation is finished, let’s check if the UniFi server is online:
systemctl status unifi

Success! If everything is good, move on to the next section to learn how to use it.

UniFi Controller Configuration

In this section, you’ll learn how to configure the UniFi Network Application.
More specifically, we’ll be going over how to:

• Access the web admin portal.
• Add an access point.
• Create a wireless network.

Let’s cover each step in detail.

First Access

To access the web interface, go to https://<IP>:8443
You should have gotten this link at the end of the installation earlier.
For example, in my case it’s https://192.168.30.19:8443/

Don’t forget the https:// or you’ll get an error saying “bad request…requires TLS.”
When the page loads, you’ll get a warning because we don’t have a secure certificate. This is normal. Approve the exception to continue.

Now you’ll be asked to configure the initial settings for your server:

• Start by giving your UniFi server a name.
  
• Log in to your UniFi account.
  It depends on what you’re trying to do here.
  
  • If you need access to the cloud interface, which is useful for administering remote sites, you’ll want to Create Account and then log in with your UI Account.
  • If you’re always on the same network (at home for instance) and you don’t need the cloud panel, like me, you can click Advanced Setup > Skip to avoid having to create an account. You’ll then be asked to create a local account for logging in.
• Step 3: After you complete whichever path you chose above, you should be done and will now be redirected to your dashboard.

Good job! We can finally see it and configure more things if needed.

Web Interface Overview

Once logged in the web interface, you’ll get many submenus to manage everything.
For the moment, it should be pretty empty, but in the left bar you can see:

• Dashboard: Here you can have a preview of your network, like the number of APs, clients, and your network performance.
  
• Topology: In this one you can upload a map of your building, and place all APs on it.
  This way you can know where they are and see the global Wi-Fi coverage (approximately).
• UniFi Devices: This page shows you all the UniFi network devices you have on your network.
  It’s the most important page, you will manage APs from here.
• Clients: Same thing except for the clients. You’ll see here all the connected clients with information about them (IP, AP, network usage, …):
  

  

• Insights: Here you can see miscellaneous information.
  I’m using this mainly to see known clients (not connected now, but you can check the history, block or unblock them).
• Admins: this page lets you manage which users can administer this portal.
• Settings: It’s pretty important so I don’t know why this is at the very bottom. This is the page where you’ll configure everything. We’ll use it to create the wireless network.
• Logs: Here you can read through logs to find out if there’s something wrong.

Now that you have visited the whole interface, we can move forward to configure the access point.

Add the First Access Point

Physical Preparation

There are two possibilities for the access point cabling.

With a PoE switch:

• Plug the access point to the POE Switch with an RJ45 cable.
• Basically, that’s it.
  The status light should turn on and you can move to the next step.

Without PoE switch:

• You must have a POE adapter like this:
  

  

  (it’s available on Amazon if you don’t have one with your access point: check it here).
• Connect the LAN port to your switch or wall network socket.
• Connect the POE port to the access point.
• If the access point LED starts to blink, it’s ok.

Software Configuration

Now that we powered on the access point, we can go back to the Unifi web interface for the next steps:

• Access the web interface: https://IP:8443.
• Click on UniFi Devices in the left menu.
• You should now see your access point in the list:
  

  

  The controller is seeing it, but we need to tell that it’s an access point for this controller.
• Click on “Adopt” at the end of the line.
  The adoption process starts, after a few seconds, you should get the “Connected” status.
  

  

• If needed (probably), you can upgrade the AP firmware to the latest version by clicking “Upgrade”.
  Your access point will take a few minutes to download and update the firmware.
  

  

Anyway, the first access point is ready, and we can now create the wireless network (SSID).

You can click on the line to see and change other settings for the access point (on the right).

For example, you can set an alias for each access point to know which one is which.
In the properties window, click on the config tab and set an alias.

Change everything you want on the access point and move to the SSID creation.

Create a Wireless Network

Creating a wireless network is basically setting an SSID, a password and a security type.
You can do this in the “Settings” menu from the left bar:

• Go to Settings and click on WiFi.
• Then click the Create New button:
  

  

• In the new window, choose an SSID name, a network passphrase (preferably a long one from 15-30 characters, so your Wi-Fi doesn’t get hacked), and lots of other options, like if you want to broadcast dual-band.
  

  

• If you want to tweak even more settings, change Advanced to Manual. There you can choose what security type you want, like WPA2/WPA3.
• When you’re done, click Create at the very bottom to save.

The access points will restart with the new settings.
After a few seconds, the new wireless network is available for all your devices.

Connect to it and check that everything works fine.
By default, the Unifi controller will give you an IP address within your main network.
You have nothing else to do, but you can change it in Settings > LAN.

Then go back to the different menus to see information and statistics about your device.
Enjoy 🙂

That’s it, you know how to install and configure a Unifi controller on your Raspberry Pi.
This controller is running perfectly on my Raspberry Pi (3B+ and 4).
I don’t know how many clients it would handle, but at home it’s more than enough.

Related Questions

How do I update the Unifi Network Application?

GlennR, the script’s maintainer, also provides an easy update script:

• Download the Unifi Network Application updater:
  wget https://get.glennr.nl/unifi/update/unifi-update.sh
• Run the script:
  sudo bash unifi-update.sh

If you want this easy script to keep working on your Pi in the future, consider supporting GlennR. He makes new versions for every update that you can find here.

Do I need to keep the Raspberry Pi on?

Not really. As soon as the Raspberry Pi stops, the controller admin portal is no longer accessible but the access points will continue to work. You can still access the Wi-Fi network, but you lose controller’s features like roaming between APs.

Does the UniFi server have advanced features you didn’t mention?

Yes, way too many. I made a quick tutorial, but you can do a lot more: schedule downtimes, create guest access with VLAN or not, Radius with Active Directory, filter MAC address, block and unblock clients, etc …

How do I reset a UniFi access point?

If you lose access to an access point or have strange scenarios in the adoption process, you can reset it to factory defaults. To do this, use the reset button near the RJ45 socket. While the access point is on, let the button pressed for 10 seconds and then wait for the reset.

Not getting the same result?

Even when you follow every step, small differences in OS version, hardware or config can change the outcome. Instead of wasting time guessing, get help from people who have already fixed the same kind of issue.

Ask your question now →

🔒 No risk. Cancel anytime.

• Get help on your exact issue
• Access step-by-step videos for tricky setups
• Browse the website without ads