Easy Guide to Installing UniFi Controller on Ubuntu Server 24.04

Installing the UniFi Controller Doesn’t Have to Be Complicated. Follow This Easy Guide for a Smooth Setup.

Introduction to UniFi Controller and Benefits of Proxmox Deployment

The UniFi Controller by Ubiquiti is an advanced network management platform that enables users to seamlessly monitor, configure, and optimize their network infrastructure.

With this Controller, you can manage multiple UniFi devices—including access points, switches, and gateways—from a single, intuitive interface. Installing the controller on an Ubuntu Server 24.04 VM within Proxmox not only offers a self-hosted, cost-effective solution but also enhances control and flexibility in managing network environments.

In this guide, we’ll cover each step of the installation process, from setting up dependencies to fine-tuning configurations, ensuring you have a smooth, efficient deployment tailored to your specific network needs. Whether for a home network or a business environment, this setup will empower you with comprehensive, centralized network management at your fingertips.

Prerequisites and System Requirements

Before installing the UniFi Controller on an Ubuntu Server 24.04 virtual machine in Proxmox, make sure you have the following prerequisites in place:

1. Ubuntu Server 24.04:
   A VM running Ubuntu Server 24.04 set up in Proxmox. (Refer to our setup guide if you need assistance with this step.)
2. Access to Proxmox VE:
   Ensure you have administrative access to your Proxmox Virtual Environment to create and manage VMs.
3. Internet Connection:
   The VM must have internet access to download necessary packages and updates.
4. Basic Linux Knowledge:
   Familiarity with basic Linux commands will be helpful in navigating the setup process.
5. OpenSSH Server (Optional but recommended):
   Allows remote access, making it easier to manage the installation and future maintenance.

To run the Controller smoothly, make sure your VM meets the following recommended specifications:

• CPU:
  At least 2 CPU cores. (UniFi Controller performs better with more cores if managing multiple devices.)
• RAM:
  Minimum 2 GB RAM, although 4 GB or more is recommended for better performance.
• Storage:
  At least 20 GB of free disk space. UniFi Controller requires space for logs, databases, and updates.
• Network Configuration:
  Ensure that the VM is configured with a static IP address (recommended) or a reserved DHCP lease for stable network connectivity.

With these prerequisites and system requirements in place, you’re ready to proceed with the UniFi Controller installation on your Ubuntu Server VM.

Important: Before Continuing with the Installation – In Proxmox Check These Settings on your VM

The VM needs to be off to change these settings.

CPU Type: host

Setting the CPU type to host allows the VM to directly use the capabilities of the host’s physical CPU. This provides the best compatibility and performance by enabling access to all instruction sets and optimizations available on the actual CPU, which helps prevent compatibility issues.

Note: I had to change this setting myself, as I encountered issues with MongoDB not starting and throwing Core Dump errors. Switching to the ‘host‘ CPU type resolved these problems.

Relevant CPU Flags (tick advanced)

These flags are recommended for enhanced performance and security:

• aes: Enables the AES (Advanced Encryption Standard) instruction set, allowing hardware-accelerated encryption. This improves performance for applications that rely on encryption, such as MongoDB or other secure services.
• pcid: Activates an optimization for Meltdown mitigation on certain Intel CPUs, helping reduce the performance impact of security mitigations, especially on older hardware.
• md-clear: Informs to the VM’s guest OS that MDS (Microarchitectural Data Sampling) mitigations are in place, which is useful for improving security and stability, especially if these mitigations are also applied on the host system.

These adjustments improve compatibility, security, and performance for your VM.

Installing the UniFi Controller on Ubuntu Server

Start by updating your Ubuntu Server System Package list

sudo apt update

This command refreshes the local package list, ensuring that your system has the latest information on available software versions and dependencies. This is an important step before installing or updating any packages, as it helps avoid conflicts and ensures you’re working with the most current versions of the software available in the repositories.

Install several necessary packages on your Ubuntu system:

sudo apt install curl haveged gpg openjdk-17-jre-headless -y

This command installs several necessary packages on your Ubuntu system

• curl: A tool for transferring data from or to a server, commonly used to download files or interact with web API’s.
• haveged: A daemon that provides additional entropy for the Linux kernel’s random number generator, improving security by ensuring enough randomness.
• gpg: The GNU Privacy Guard, used for encrypting and signing data, often necessary for verifying downloaded packages.
• openjdk-17-jre-headless: A headless version of the Java Runtime Environment (JRE) 17, which is used to run Java applications without a graphical user interface (GUI). This is needed for running the Controller, as it relies on Java.
• -y: automatically answers “yes” to any prompts that might appear during the installation process.

Together, these packages prepare your system for the UniFi Controller installation by ensuring it has the tools, security, and runtime environment needed to function properly.

Add the repository for to Ubuntu

This command adds the official repository’s GPG key to your Ubuntu system’s keyring, which is necessary for verifying packages from Ubiquiti’s repository.

curl https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg >/dev/null

Here’s a breakdown of what each part does:

• curl https://dl.ui.com/unifi/unifi-repo.gpg: Downloads the GPG key file from Ubiquiti’s server, which is used to authenticate packages from the repository.
• |: Pipes the downloaded data to the next command.
• sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg: Saves (or “tees”) the downloaded GPG key into the file /usr/share/keyrings/ubiquiti-archive-keyring.gpg. Using sudo here allows the command to write the file to a protected directory, which requires root privileges.
• >/dev/null: Suppresses the output of the tee command, so nothing is displayed in the terminal.

Add the repository to your system

echo 'deb [signed-by=/usr/share/keyrings/ubiquiti-archive-keyring.gpg] https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list > /dev/null

How to Add MongoDB 7.0 Repository and GPG Key to Ubuntu for Secure Installation

curl https://pgp.mongodb.com/server-7.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-org-server-7.0-archive-keyring.gpg && \
echo 'deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-org-server-7.0-archive-keyring.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse' | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list > /dev/null

Copy the whole code

Explanation of What These Combined Commands Do:

This combined command performs two key actions to set up the MongoDB 7.0 repository on an Ubuntu system:

1. Adds the MongoDB GPG Key:
   • The first part downloads MongoDB’s GPG key for version 7.0 and converts it to binary format. It then saves the key in the /usr/share/keyrings/ directory as mongodb-org-server-7.0-archive-keyring.gpg. This key is used to verify MongoDB packages, ensuring they are authentic and come from MongoDB’s official repository.
2. Adds the MongoDB Repository:
   • The second part adds the MongoDB 7.0 repository to Ubuntu by creating a new source list file at /etc/apt/sources.list.d/mongodb-org-7.0.list. It specifies the repository URL along with the architecture (amd64, arm64) and links the repository to the previously downloaded GPG key using the signed-by= option. This setup allows Ubuntu to securely download and install MongoDB packages from this repository.

This setup enables secure and authenticated installation of MongoDB packages from the official MongoDB repository.

Install and Run MongoDB

To install and run MongoDB, use the following command sequence:

sudo apt update && sudo apt install mongodb-org-server -y && sudo systemctl enable mongod && sudo systemctl start mongod

1. sudo apt update: Updates the local package list, ensuring that you have the latest information on available versions and dependencies for all packages. This step is essential for installing up-to-date software.
2. sudo apt install mongodb-org-server -y: Installs the MongoDB server package. The -y flag automatically confirms the installation, so it proceeds without needing manual confirmation.
3. sudo systemctl enable mongod: Enables the MongoDB service (mongod) to start automatically when the system boots. This ensures that MongoDB will run after each reboot.
4. sudo systemctl start mongod: Starts the MongoDB service immediately, so you don’t have to reboot to get it running. This allows you to begin using MongoDB right after installation.

In summary, this command sequence updates the package list, installs MongoDB, configures it to start on boot, and immediately starts the MongoDB service.

Verify That MongoDB Is Running

Before continuing the installation, check that MongoDB is running by using the following command:

sudo systemctl status mongod

It should look like this:

Press CTRL+C when done checking.

Installing the UniFi Controller

sudo apt install unifi -y

Explanation:

• sudo: Runs the command with superuser (administrator) privileges. Installing software requires elevated permissions.
• apt install: Uses the apt package manager to install a specified package. In this case, it’s used to install the unifi package.
• unifi: The package name for the UniFi Controller software. When unifi is available in your repository sources, this command will install the UniFi Controller software, which provides a centralized interface for managing UniFi devices such as access points, switches, and routers.
• -y: automatically answers “yes” to any prompts that might appear during the installation process.

Summary

This command installs the Controller software on your system, allowing you to set up and manage UniFi network devices from a web-based interface.

Please note that this may take some time. If it hangs for 10 or more minutes, try CTRL+C and retry the command.

Troubleshooting the Installation of The Controller:

If you have problems installing the controller, check these things:

1. Check that MongoDB is running: sudo service mongod status
2. Check MongoDB logs: sudo tail -f /var/log/mongodb/mongod.log
3. Confirm that you have enough available RAM: free -h
4. Verify Disk Space: df -h

Accessing the Controller Web Interface

After successfully installing the UniFi Controller from the steps above, you’re ready to access the web interface, where you can configure and manage your network devices.

1. Find Your Server’s IP Address: If you don’t know the IP address of your Ubuntu server, open a terminal on the server and type:
   ip add

   Look for the inet address under the network interface (often labeled as eth0 or ens33). This is your server’s IP address. Ignore any address that appears as 127.0.0.1/8, as this is the loopback address and not your network IP.

2. Open a Web Browser: Open your preferred web browser on a computer connected to the same network as the UniFi Controller.
3. Enter the Controller’s IP Address and Port: In the address bar, enter the IP address you just found, followed by :8443. The format should look like this:
   https://<server-ip>:8443

   Replace <server-ip> with the actual IP address of your Ubuntu server.

4. Accept the Security Warning: Since the UniFi Controller uses a self-signed SSL certificate by default, you may see a security warning. Accept this warning to proceed to the login page.
5. Complete the Initial Setup Wizard: The first time you access the web interface, you’ll be guided through an initial setup wizard. Here, you can:
   • Create an admin account for the Controller.
   • Configure basic settings for your network.
   • Set up cloud access if you want remote management through UniFi’s cloud services.
   • To skip registering a UniFi account, click on ‘Advanced Setup‘ under the ‘Sign In to Your UI Account‘, press ‘Skip‘. Then create an admin account. You’ll still need to add an email account.
6. Begin Managing Your Network: Once the setup is complete, you’ll be taken to the UniFi Dashboard, where you can start adding and managing UniFi devices, view network statistics, configure settings, and monitor network performance.

Tips and Tricks for Using UniFi Controller

1. Enable Dark Mode
To reduce eye strain and enhance the interface, enable Dark Mode:

• Go to Settings -> System -> Theme: Dark -> Apply Changes

2. Troubleshooting Device Visibility
If your devices aren’t showing up in the UniFi Controller, try these steps:

• Reset Devices: Sometimes, a simple reset can help UniFi devices (such as access points, switches, or firewalls) reconnect to the controller. Power cycle them or perform a factory reset if necessary.
• Check VLANs: If you have VLANs configured, UniFi devices may not appear immediately. Ensure the VLANs are set up correctly on both the controller and devices. Also, check if there are any firewall rules blocking the port for STUN: 3478/UDP
• SSH into Devices: If the devices still aren’t showing, the STUN server configuration might be incorrect. To fix this, SSH into each device and manually check or configure the STUN server:
  • First, locate the device’s IP address by checking your router’s DHCP server (you should able to find your UniFi device by searching for its hardware / MAC address).
  • Use SSH to connect to the device by entering its IP address, and verify or update the STUN settings as needed.
  • Default credentials for Ubiquiti gear is: Username: ubnt | Password: ubnt

These steps should help troubleshoot common issues and improve your experience with the UniFi Controller.

Updating the Controller

To update the controller, simply type the command:

sudo apt-get update && sudo apt-get upgrade -y

Explanation:

1. sudo apt-get update: This command refreshes the local package index, ensuring your system has the latest information on available packages and updates from all configured repositories, including the UniFi repository.
2. sudo apt-get upgrade -y: This command installs the latest versions of all installed packages, including the UniFi Controller if an update is available in the repository. The -y flag automatically confirms the upgrade, so you won’t be prompted for confirmation.

By running this command, you keep your UniFi Controller up to date with the latest features and security patches.

(Optional) Enabling Firewall for Security

Enabling the UFW (Uncomplicated Firewall) is a simple yet effective way to protect your server. Even if it’s a local server with no external access, adding this layer of security can be beneficial. After all, you can never be too safe.

In this step, we’ll enable and configure a firewall to help protect your server from unauthorized access.

We will allow multiple ports for the UniFi Controller to work as intended.

TCP Ports to Open

• 22 – Allows SSH for remote access.
• 8443 – UniFi Controller Web Interface for configuration and monitoring.
• 8880 – HTTP redirect for the UniFi guest portal.
• 8843 – HTTPS redirect for the UniFi guest portal.
• 8080 – Device Inform port for communication between UniFi devices and the controller.

UDP Ports to Open

• 3478 – STUN for NAT traversal, allowing devices to communicate with the controller.
• 10001 – Device Discovery on the local network for new UniFi devices.

To allow all these ports simply run the following command:

sudo ufw allow 22,8443,8880,8843,8080/tcp && sudo ufw allow 3478,10001/udp

Activating the Firewall

After adding these ports, we need to active the firewall. Use the following command:

sudo ufw enable -y

Press ‘Y’ for Yes, then click enter.

Verify That the Ports Are Added Correctly

Check that the ports are added correctly. Use the following command:

sudo ufw status

This command will display the list of all allowed ports and rules in UFW, confirming that everything is set up as expected.

Enable logging and how to check them

To keep track of incoming and outgoing connections, it’s a good idea to enable logging in UFW. This helps monitor traffic, detect unauthorized access attempts, and troubleshoot firewall issues. To enable logging, use the following command:

sudo ufw logging on

This command activates logging, starting with the default log level, which is usually set to “low” in UFW. You can also adjust the log level to control how much detail is logged:

• Low: Only logs denied connections.
• Medium: Logs denied connections with some additional details.
• High: Logs all connections, both allowed and denied, which can be useful for detailed monitoring but may fill up logs quickly.

To change the log level, use:

sudo ufw logging medium (low | medium | high)

Checking Firewall Logs:

Once logging is enabled, UFW logs are typically stored in the syslog file. You can view the logs by using:

sudo tail -f /var/log/syslog

This command shows the latest entries in the syslog file in real-time, including UFW logs. Look for entries that mention “UFW” to find firewall-related logs.

For a more detailed view, you can use grep to filter only UFW entries:

sudo grep UFW /var/log/syslog

Summary: Enabling UFW logging helps track and analyze firewall activity. You can adjust the log level based on your needs and view the logs in the syslog file to monitor your system’s network activity.