# UniFi Network Controller

> UniFi Network Application with MongoDB.

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: unifi-controller, mongodb
- Tags: unifi, network, wifi, controller
- Source: https://docker.recipes/homelab/unifi-network-stack

## Overview

UniFi Network Application is Ubiquiti's centralized management platform for UniFi networking equipment, including wireless access points, switches, routers, and security cameras. Originally designed as the UniFi Controller, it has evolved into a comprehensive network management solution that provides real-time monitoring, configuration management, and analytics for enterprise and prosumer networking deployments. The platform offers features like guest portal management, bandwidth monitoring, VLAN configuration, and detailed network analytics through an intuitive web interface.

This deployment consists of two separate services: a MongoDB 4.4 database (unifi-db) for persistent data storage and the UniFi Network Application container (unifi-controller) running the LinuxServer.io image. The MongoDB instance is specifically configured for UniFi with a dedicated database and user credentials, while the controller connects to it for storing device configurations, user data, network statistics, and historical analytics. The setup includes proper database initialization scripts and environment variable configuration for automatic connection establishment.

This stack is ideal for home lab enthusiasts, small to medium businesses, and network administrators who need centralized management of UniFi devices without the complexity of UniFi Cloud Key hardware. The containerized approach provides flexibility for deployment on various platforms while maintaining data persistence and easy backup capabilities, making it perfect for those who want full control over their network management infrastructure.

## Features

- MongoDB 4.4 backend with automatic UniFi database and user initialization
- Comprehensive UniFi device adoption and management through web interface on port 8443
- STUN server functionality on UDP port 3478 for NAT traversal and device communication
- Device discovery service on UDP port 10001 for automatic UniFi hardware detection
- Guest portal and captive portal management with customizable authentication
- Real-time network analytics and historical data visualization
- VLAN management and advanced networking configuration
- Automated device firmware updates and centralized configuration deployment

## Use cases

- Home lab networking with multiple UniFi access points and switches requiring centralized management
- Small office deployments needing guest network isolation and bandwidth monitoring
- Remote site management where UniFi Cloud Key hardware is not practical or cost-effective
- Network administrators who require detailed analytics and historical data retention
- Organizations needing custom guest portal branding and authentication workflows
- Multi-tenant environments requiring VLAN segmentation and access control
- Educational institutions managing student and staff network access with time-based restrictions

## Prerequisites

- Minimum 2GB RAM recommended for combined MongoDB and UniFi Controller operation
- Network access to UDP ports 3478 and 10001 for device adoption and STUN services
- HTTPS certificate management knowledge for secure web interface access
- UniFi network hardware (access points, switches, or gateways) to manage
- Understanding of network topology for proper device adoption and inform URL configuration
- MongoDB password configuration through MONGO_PASSWORD environment variable

## docker-compose.yml

```yaml
services:
  unifi-db:
    image: mongo:4.4
    container_name: unifi-db
    restart: unless-stopped
    volumes:
      - unifi_db_data:/data/db
      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro

  unifi-controller:
    image: linuxserver/unifi-network-application:latest
    container_name: unifi-controller
    restart: unless-stopped
    ports:
      - "${UNIFI_PORT:-8443}:8443"
      - "3478:3478/udp"
      - "10001:10001/udp"
      - "8080:8080"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ:-UTC}
      - MONGO_HOST=unifi-db
      - MONGO_PORT=27017
      - MONGO_DBNAME=unifi
      - MONGO_USER=unifi
      - MONGO_PASS=${MONGO_PASSWORD}
    volumes:
      - unifi_config:/config
    depends_on:
      - unifi-db

volumes:
  unifi_db_data:
  unifi_config:
```

## .env

```bash
# UniFi Controller
UNIFI_PORT=8443
TZ=UTC
MONGO_PASSWORD=unifi_password
```

## Usage notes

- UniFi at https://localhost:8443
- Create init-mongo.js for DB
- Adopt devices via inform URL
- UDP ports for STUN/discovery

## Troubleshooting

- UniFi devices stuck in adoption loop: Verify UDP ports 3478 and 10001 are accessible and check inform URL configuration matches controller IP
- MongoDB connection failures on startup: Ensure init-mongo.js script is properly mounted and MONGO_PASSWORD environment variable is set
- Web interface inaccessible at https://localhost:8443: Check SSL certificate generation and verify container has proper PUID/PGID permissions
- Device discovery not working: Confirm Layer 2 network connectivity and that devices are on same broadcast domain as controller
- Database corruption after container restart: Verify unifi_db_data volume has proper filesystem permissions and adequate disk space
- High memory usage from unifi-controller: Monitor MongoDB memory usage and consider increasing container memory limits or optimizing database queries

