UniFi Network Controller

intermediate

UniFi Network Application with MongoDB.

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.

Key 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

Common Use Cases

1Home lab networking with multiple UniFi access points and switches requiring centralized management
2Small office deployments needing guest network isolation and bandwidth monitoring
3Remote site management where UniFi Cloud Key hardware is not practical or cost-effective
4Network administrators who require detailed analytics and historical data retention
5Organizations needing custom guest portal branding and authentication workflows
6Multi-tenant environments requiring VLAN segmentation and access control
7Educational 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

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

docker-compose.yml

1services: 
2  unifi-db: 
3    image: mongo:4.4
4    container_name: unifi-db
5    restart: unless-stopped
6    volumes: 
7      - unifi_db_data:/data/db
8      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro
9
10  unifi-controller: 
11    image: linuxserver/unifi-network-application:latest
12    container_name: unifi-controller
13    restart: unless-stopped
14    ports: 
15      - "${UNIFI_PORT:-8443}:8443"
16      - "3478:3478/udp"
17      - "10001:10001/udp"
18      - "8080:8080"
19    environment: 
20      - PUID=1000
21      - PGID=1000
22      - TZ=${TZ:-UTC}
23      - MONGO_HOST=unifi-db
24      - MONGO_PORT=27017
25      - MONGO_DBNAME=unifi
26      - MONGO_USER=unifi
27      - MONGO_PASS=${MONGO_PASSWORD}
28    volumes: 
29      - unifi_config:/config
30    depends_on: 
31      - unifi-db
32
33volumes: 
34  unifi_db_data: 
35  unifi_config:

.env Template

.env

1# UniFi Controller
2UNIFI_PORT=8443
3TZ=UTC
4MONGO_PASSWORD=unifi_password

Usage Notes

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

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

unifi-db

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  unifi-db:
5    image: mongo:4.4
6    container_name: unifi-db
7    restart: unless-stopped
8    volumes:
9      - unifi_db_data:/data/db
10      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro
11
12  unifi-controller:
13    image: linuxserver/unifi-network-application:latest
14    container_name: unifi-controller
15    restart: unless-stopped
16    ports:
17      - "${UNIFI_PORT:-8443}:8443"
18      - "3478:3478/udp"
19      - "10001:10001/udp"
20      - "8080:8080"
21    environment:
22      - PUID=1000
23      - PGID=1000
24      - TZ=${TZ:-UTC}
25      - MONGO_HOST=unifi-db
26      - MONGO_PORT=27017
27      - MONGO_DBNAME=unifi
28      - MONGO_USER=unifi
29      - MONGO_PASS=${MONGO_PASSWORD}
30    volumes:
31      - unifi_config:/config
32    depends_on:
33      - unifi-db
34
35volumes:
36  unifi_db_data:
37  unifi_config:
38EOF
39
40# 2. Create the .env file
41cat > .env << 'EOF'
42# UniFi Controller
43UNIFI_PORT=8443
44TZ=UTC
45MONGO_PASSWORD=unifi_password
46EOF
47
48# 3. Start the services
49docker compose up -d
50
51# 4. View logs
52docker 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-network-stack/run | bash

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

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-controllermongodb

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download