How to install and configure Unifi controller on Raspberry Pi?

install Unifi controller on raspberry pi

If you have already managed multiple Wi-Fi access points, you should know that this can be a nightmare …
But with good choices for hardware and a controller, this becomes easier
It’s the main goal of the Unifi controller: manage most of the tasks on a wireless network to avoid issues
And it’s available for Raspberry Pi, so we like that 🙂

How to install and configure Unifi controller on Raspberry Pi?
The Unifi controller is not available in the Raspbian repository
You need to add the Ubiquiti repository to manage the package with apt
You can also download the Debian package on the official website

The installation 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

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 the solar technology, they help you to manage solar farms

Anyway, the product that interests us today is a software: Unifi controller
The goal of this product is to manage access points and wireless devices from a unique web interface
From the interface, 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 needs at home if you get some issues with your Wi-Fi connection (rooms with no network, roaming, stability, etc.)
If you need over one access point to cover all the house, it could be interesting to install these products at home

For example, let’s say you install three access points and the controller somewhere
You’ll have only one Wi-Fi SSID in all the area (outdoor included)
And you can move from one side to another without disconnection

Ubiquiti products

Ubiquiti products are distributed by resellers, but are also available on Amazon for example

To test these products, you don’t need many things
Just buy one or more access points on Amazon and build your professional wireless network

Here is the link: Ubiquiti Unifi AP
You have several packages available: Only one, 2 AP, 4 AP, etc
Choose the one you prefer, but there is not a big saving by taking big packs, so you can try with one or two, and order the others after

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

Whatever your choice, a PoE switch will make the installation easier
If you want to start without it, they provide 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 controller installation

Now that you understand what are the Unifi products, we can move to the controller installation

Raspbian installation

As for any tutorial on this site, you firstly need to install Raspbian on your Raspberry Pi
Any version will do the job (I’m doing it with Raspbian Lite)
If you don’t know how to do this, read my article on How to install Raspbian on your Raspberry Pi

Once installed, update it and reboot:
sudo apt update
sudo apt upgrade
sudo reboot

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

Set a static IP address

As our Raspberry Pi will be like 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 (at home it’s probably ok)
  • 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 use the DHCP to get a random IP among those available

For the static IP, you can either fix the IP in the DHCP server (your Internet router probably), or set a static IP in the Raspberry Pi configuration

If you don’t know how to do this, I already explained it at the end of this article: Set a static IP address on your Raspberry Pi

Unifi controller installation

Now we are ready to start the installation
For these steps you have two choices:

  • Download and install directly the official Debian package from the website
  • Add a new repository to manage the Unifi package with apt

On the Ubiquiti downloads page you can find the Debian package to install the controller
You can download it and install it on your Raspberry Pi
But I don’t recommend it.

Because the Controller has many updates, about every month you have to download and install a new version manually
There is a repository available and it’s easier to manage all updates with apt rather than doing everything manually

  • Connect with SSH to your Raspberry Pi
  • Add the repository in the apt configuration file
    echo 'deb https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list
  • Add the key to the trusted keys
    sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg
    This allows us to use software from the previous repository
  • Run apt update to update the available packages list
    sudo apt update
  • And finally, install the Unifi package
    sudo apt install unifi
    Answer yes and wait a few seconds for the installation process to finish

This is the end of the installation procedure, but your controller is not working yet
If you check the service status with:
sudo service unifi status
You’ll probably get an error like this one on a fresh Raspbian installation:

Starting Ubiquiti UniFi Controller: unifi
Cannot locate Java Home

Yes, you need to install Java to start the Unifi service
And also, the only version currently supported is Java 8
Here is how to install it:
sudo apt install openjdk-8-jre
And finally start the Unifi service:
sudo service unifi start

Check the status again if you want

If everything is ok, you can move on to the next part to know how to use the software

Unifi controller configuration

First access

To access the web interface, go to https://<IP>:8443
For example, in my case it’s https://192.168.1.25:8443/
You’ll get a browser warning because we don’t have a secured certificate for the moment

Accept the exception and move to the next page to configure everything you need to get started:

  • Step1: Start by giving a name to his controller and click on “Next”
  • Step 2: Choose if you want to enable the cloud interface (default) or not (advanced)
    It depends on what you are trying to do
    If you are always on the same network (home or in a company), you don’t really need the cloud panel. But it can be useful for remote sites.
    • If you keep the default option, fill the form to create an Unifi account
    • On the advanced option, you have a form like this:

      If you enable one option, you need to create a cloud account AND a local account
      I don’t need it for my test, so I disable everything
  • Step 3: Sign in or configure options
    This step is also different depending on your choice in the previous step
    You may need to sign in your account, or just to configure two additional options (auto backup and auto-optimize).
    Keep them enabled if asked
  • Step 4: Configure your devices

    You can just skip this, it’s not required for now. You can add devices at anytime in the interface
  • Step5: You can finally configure your Wi-Fi settings now

    You can also change this in the interface, so just pick something to get started
  • Step6: Finally, you also need to review your settings and you are ready to go

Good job! You will now be redirected to the web panel
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 performance (number of APs and clients)
    Most of this dashboard needs the Unifi Security Gateway, so it’s not an important page
  • Statistics: In this page you can monitor clients and traffic in the whole network
    For the moment, nothing here 🙂
  • Map: 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)
  • Devices: This page shows you all the Unifi devices you have on your network
    It’s the most important page, you will manage APs from here
  • Clients: Same thing 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)
  • Events: This window shows you all the recent logs on your network
    This can be clients connections, AP upgrades, roaming, …
  • Alerts: Same thing with errors and warnings
  • Settings: And this is the page where you’ll configure everything
    We’ll use it to create the wireless network
  • Chat support: If you need help from Unifi, you can ask for help here

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:
    unifi poe adapter
    (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 “Devices” in the left menu
  • You should now see your access point in the list:
    unifi ap pending adoption
    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
    unifi ap connected
  • 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
    unifi ap upgrade

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

unifi ap properties

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

unifi set alias access point
unifi access point new name

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 your 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:

  • In settings, click on “Wireless Networks”
  • Then click on the “Create a new wireless network” button
    create new network
  • In the new window, choose an SSID, a security type and a password
    new wireless network creation
    Choose WPA-Personal for security, WEP is not secure
    And prefer a long password (ideally a phrase from 15 to 30 characters)
  • Click “Save”

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

unifi wifi windows

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 🙂

Related questions

Do I need to keep the Raspberry Pi on? Not really. As soon as the Raspberry Pi stops, the controller is no longer available but the access point continue to work. You can still access the Wi-Fi network, but you lose controller’s features like roaming between APs

Do the Unifi controller have advanced features you don’t talk about? Yes, a lot. 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 to reset an 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.

Conclusion

That’s it, you know how to install and configure an 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

If you have questions on this topic, leave a comment below and I’ll help you
I’m using this software at work for five years now, so I may have the answer 😉

How useful was this post?

Click on a star to rate it!

Average rating 5 / 5. Vote count: 4

No votes so far! Be the first to rate this post.

As you found this post useful...

Spread the word!

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?

12 comments

  1. Ken Reply

    Configuration recommendations?

    I’ve found that iOS devices seem to have trouble connecting if not close to the AP. The result is incorrect password but the devices connect fine when close.

    Seems odd behavior for these enterprise APs.

    Thanks
    Ken

  2. Jeff Reply

    I have yet to get this awesome (thanks for making it straight forward!) guide to work.. I realize it may be outdated and some dependencies or OS version may be effecting things. Would be great if someone could help update. Im still working at it.. (i have a working install of unifi but had to do it a very complicated way which made a mess out of the install).

    Ill post if i figure i out. Otherwise ill use my bloated install for now.

    • jeff Reply

      Edit.. Ok well 3rd time is the charm i guess.. I literally ran every command 3x.. and it finally worked when i did an apt update and it gave warnings on how unifi package has been configured multiple times…

      • JEFF Reply

        Main error preventing me was Signatures could not be verified as public key is not available. Request issues/else? Or does it override after so many attempts to NOKEY?

  3. Søren Hansen Reply

    Hi.
    After running through the guide, I’m almost happy.
    Things seem to be fine on the Raspberry, but it doens’t answer at port 8443.
    How can I verify the installation?
    What can be wrong?
    I hope you can help me.

    • Patrick Fromaget Post authorReply

      Hi Søren,

      Did you try HTTP and HTTPS?

      I think it’s https by default
      sudo service unifi status is running ?

      • Søren Hansen Reply

        I use the adress https://192.168.1.15:8443. I looks like the port 8443 is blocked on the respberry. Is there a way to open that port?
        How do I make the sudo service running?

        Sorry, I’m very new to the Raspberry.

        • Patrick Fromaget Post authorReply

          The service will open the port on start

          sudo service unifi status
          sudo service unifi start
          sudo service unifi stop

          If it doesn’t work, you can check the logs to find the error (/var/log/syslog for example)

  4. Patrick Fromaget Post authorReply

    Hello everyone,

    For information, I just updated this post

    The installation and the welcome wizard was a bit different, so this is now up to date
    I couldn’t update the screenshots on the access point adoption process due to the current lockdown. But it should be almost the same

    Let me know if you have any issues

  5. Chris Reply

    Thank you for the article. It was most helpful. The only problem I ran into was access the URL for the controller. IE, Edge, Chrome, Brave all indicated this error: ERR_SSL_VERSION_OR_CIPHER_MISMATCH. Being I had not restarted the RPi after all the steps, I decided to reboot and the problem went away. 🙂 Really great site you have!

Leave a Reply to jeff Cancel reply

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