Guide

UniFi Network Controller Deployment

UniFi Controller Role

The UniFi Network Controller provides centralized management for UniFi network devices including gateways, switches, and access points. It acts as the management plane for configuration, monitoring, adoption, and firmware management across the homelab network.

What This Solves?

Centralized UniFi device management
Single pane of glass for network monitoring
Simplified VLAN, WiFi, and port profile management
Self-hosted controller for local ownership
Persistent network configuration and device adoption
Scalable platform for future UniFi expansion

Skills Acquired

Network ManagementSelf-Hosted InfrastructureLinux Server AdministrationAPT Repository ManagementService ManagementUniFi AdministrationNetwork Monitoring

Overview

The UniFi Network Controller is a self-hosted network management platform used to configure, monitor, and maintain UniFi networking devices.

In this homelab environment, the controller is deployed as VM 101 and is used to manage the UniFi Gateway, switches, access points, VLANs, and wireless networks from a centralized interface.

Official Documentation

Use the official Ubiquiti Linux installation guide as the source reference for the deployment process. The APT repository configuration, GPG key, and package installation on this VM follow the patterns documented by Ubiquiti for Debian and Ubuntu based systems.

Purpose

The UniFi controller VM was deployed to solve several problems within the homelab environment:

Centralized management of UniFi devices
Easier configuration of wireless networks and VLANs
Persistent controller hosting independent of cloud dependency
Improved visibility into traffic, clients, and device health
Simplified future network expansion

Instead of relying on cloud-hosted controllers or device-local interfaces, this VM provides a dedicated management plane that stays entirely within the homelab, making it easier to audit, back up, and iterate on network design.

Services Running on This VM

This VM runs the UniFi Network application as a Linux service on a Debian or Ubuntu based system.

The application is installed using the official UniFi APT repository method and managed through standard Linux service commands. Aside from base OS services (SSH, logging, package management), the primary workload on this VM is the UniFi service itself and its supporting database components.

Infrastructure Context

This UniFi controller instance runs as VM 101 on the Proxmox hypervisor.

VM ID: 101
Role: UniFi Network Controller
Platform: Proxmox VM
OS: Debian or Ubuntu-based Linux
Management Scope: UniFi Gateway, switches, access points, VLANs, and WiFi networks

The controller is treated as the single source of truth for UniFi configuration while forwarding and data-plane traffic remains on the physical gateway and switches.

Deployment Steps

1. Create the VM in Proxmox

Create VM 101 in Proxmox, assign CPU, RAM, disk, and network resources, and install a Debian or Ubuntu based OS. Configure a static IP address appropriate for the management VLAN or network segment and update the system after installation.

2. Install required packages

Prepare the system for the UniFi APT repository by installing the required HTTPS transport and certificate packages:

sudo apt-get update && sudo apt-get install ca-certificates apt-transport-https

3. Add the UniFi APT repository

Configure the official UniFi repository so the UniFi Network application can be installed and updated via APT:

echo 'deb [ arch=amd64,arm64 ] https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

4. Add the UniFi GPG key

Import the UniFi repository GPG key using the recommended method so APT can verify UniFi packages:

sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg

5. Install UniFi Network

Update package metadata and install the UniFi Network application:

sudo apt-get update && sudo apt-get install unifi -y

6. Start and verify the service

Start the UniFi service and confirm that it is running correctly:

sudo service unifi start
sudo service unifi status

7. Access the controller

With the service running, the UniFi Network application should be reachable from the server's configured local IP in a web browser. Use HTTPS to reach the controller and complete the initial UniFi setup wizard, then adopt the UniFi Gateway, switches, and access points into this controller.

8. Ongoing service management

Daily operations on this VM are performed through standard service commands:

sudo service unifi stop
sudo service unifi restart
sudo service unifi status

9. Log file locations

When troubleshooting, UniFi logs on this VM are typically found at:

/usr/lib/unifi/logs/server.log
/usr/lib/unifi/logs/mongod.log

10. Notes and operational considerations

Back up the UniFi database before upgrades.
Use the stable release channel for production-like use.
The Linux install runs as a service and does not provide a local GUI.
In VMs or headless installs, entropy issues may occur and haveged may help.
If apt update fails after a repository release info change, apt-get update --allow-releaseinfo-change may be required.

High Level Architecture

At a high level, the UniFi controller on VM 101 acts as the management plane on Proxmox, with the UniFi Gateway, switches, access points, and client networks connected downstream. All UniFi devices phone home to this controller for configuration, monitoring, and adoption.

# Paste ASCII high-level architecture diagram here

[Proxmox Host]
     └── [VM 101: UniFi Network Controller]
             │
             ├── UniFi Gateway
             ├── UniFi Switches
             ├── UniFi Access Points
             └── Client VLANs / WiFi Networks

Troubleshooting

UniFi service not startingCheck the service status with sudo service unifi status and review server.log and mongod.log for Java or database errors, especially after OS or Java runtime upgrades.
Controller not reachable in browserConfirm the VM is powered on, the static IP is correct, and you can reach the host via ping or SSH. Verify that any host or network firewalls allow HTTPS access to the UniFi controller port.
Checking service statusUse sudo service unifi status for a quick health check, and fall back to journalctl or the UniFi log files when more detail is needed.
Reviewing logsInspect /usr/lib/unifi/logs/server.log and /usr/lib/unifi/logs/mongod.log for stack traces, port binding issues, or database startup problems.
Restarting the serviceAfter making configuration or system changes, restart with sudo service unifi restart and re-check access from the browser.
Repository update issuesIf apt-get update reports release file mismatches for the UniFi repository, re-run with --allow-releaseinfo-change or revisit the official UniFi documentation to confirm the current repository URL and configuration.