UniFi Network Controller

intermediate

UniFi Network Application with MongoDB.

[i]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

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

[!]

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

[$]docker-compose.yml

[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

[i]Usage Notes

[1]UniFi at https://localhost:8443
[2]Create init-mongo.js for DB
[3]Adopt devices via inform URL
[4]UDP 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

## Tags

#unifi#network#wifi#controller

## Category

Home Lab & Self-Hosting

## Related

Shortcuts: C CopyF FavoriteD Download