UniFi Controller

intermediate

Manage UniFi network devices.

Overview

The UniFi Controller is Ubiquiti's centralized network management platform that provides enterprise-grade control over UniFi access points, switches, gateways, and security cameras. Originally developed to simplify enterprise wireless deployments, the UniFi ecosystem has evolved into a comprehensive software-defined networking solution that allows administrators to manage entire network infrastructures through a single web interface. The controller handles device provisioning, firmware updates, user authentication, traffic analytics, and advanced networking features like VLANs and firewall rules. This Docker deployment utilizes the LinuxServer.io UniFi Controller image, which packages the Java-based UniFi Network Application into a containerized environment with proper user permissions and automatic updates. The container exposes all necessary ports for device communication, including the web interface on port 8443, the device inform service on port 8080, and STUN services on port 3478 for guest portal functionality and mobile app connectivity. The configuration leverages persistent volumes to ensure network settings, device configurations, and historical data survive container restarts. This setup is ideal for homelab enthusiasts managing multiple UniFi devices, small businesses requiring centralized network management, and IT professionals who want to isolate their network controller from other system dependencies. The containerized approach eliminates Java version conflicts, simplifies backup procedures, and enables easy migration between hosts while maintaining all network configurations and device adoption states.

Key Features

Centralized management of UniFi access points, switches, gateways, and Protect cameras through single web interface
Real-time network topology visualization with live device status and connection mapping
Deep packet inspection and traffic analytics with historical bandwidth usage reporting
Zero-touch device provisioning with automatic firmware updates and configuration deployment
Guest portal management with customizable captive pages and social media authentication
Advanced VLAN configuration and firewall rule management with traffic isolation capabilities
Mobile app integration for remote network monitoring and guest access control
Automated backup scheduling with configuration export and disaster recovery options

Common Use Cases

1Home office environments with multiple UniFi access points requiring centralized management and guest network isolation
2Small business deployments needing professional-grade WiFi management with employee and customer network separation
3Multi-tenant buildings requiring individual network isolation and bandwidth management per tenant
4Educational institutions managing student device access with time-based restrictions and content filtering
5Retail locations implementing guest WiFi with social media authentication and usage analytics
6Remote site management where IT administrators need centralized control over distributed UniFi installations
7Development environments for testing UniFi configurations before production deployment

Prerequisites

Minimum 2GB RAM and 2 CPU cores as UniFi Controller requires Java runtime with substantial memory allocation
Persistent storage with at least 10GB available space for configuration data, logs, and firmware updates
Network access to UniFi devices on the same subnet or proper Layer 3 adoption configuration with inform URL settings
Basic understanding of UniFi device adoption process and network configuration concepts
Port forwarding or firewall rules configured if managing UniFi devices across different network segments
Valid SSL certificate or acceptance of self-signed certificate warnings for HTTPS web interface access

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  unifi: 
3    image: linuxserver/unifi-controller:latest
4    container_name: unifi
5    restart: unless-stopped
6    environment: 
7      PUID: 1000
8      PGID: 1000
9    volumes: 
10      - unifi_config:/config
11    ports: 
12      - "8443:8443"
13      - "3478:3478/udp"
14      - "10001:10001/udp"
15      - "8080:8080"
16
17volumes: 
18  unifi_config:

.env Template

.env

1# No additional config needed

Usage Notes

1Docs: https://docs.linuxserver.io/images/docker-unifi-controller/
2Admin at https://localhost:8443 (self-signed cert warning)
3Port 8080 for device inform, 3478/udp for STUN
4Adopt UniFi APs, switches, and gateways
5Set controller hostname in UniFi devices or use DHCP option 43
6Backup config regularly: Settings > System > Backup

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  unifi:
5    image: linuxserver/unifi-controller:latest
6    container_name: unifi
7    restart: unless-stopped
8    environment:
9      PUID: 1000
10      PGID: 1000
11    volumes:
12      - unifi_config:/config
13    ports:
14      - "8443:8443"
15      - "3478:3478/udp"
16      - "10001:10001/udp"
17      - "8080:8080"
18
19volumes:
20  unifi_config:
21EOF
22
23# 2. Create the .env file
24cat > .env << 'EOF'
25# No additional config needed
26EOF
27
28# 3. Start the services
29docker compose up -d
30
31# 4. View logs
32docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/unifi-controller/run | bash

Troubleshooting

UniFi devices stuck in 'Pending Adoption' state: Verify devices can reach controller IP on port 8080 and check inform URL settings in device SSH interface
Controller shows 'Database Error' or fails to start: Check available disk space and ensure proper file permissions for mounted volume directory
Mobile app cannot connect to controller: Confirm port 3478/UDP is accessible and not blocked by firewall rules
Devices show as 'Disconnected' after container restart: Wait 5-10 minutes for device check-ins or manually restart affected UniFi devices
Web interface displays 'This site can't provide a secure connection': Accept self-signed certificate or configure custom SSL certificate in controller settings
High CPU usage and slow response times: Increase container memory allocation and disable unnecessary features like deep packet inspection on high-traffic networks

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

unifi

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download