Ditch the Cloud Key: Hosting the UniFi Network Application on Docker

The Hidden Tax of Centralized Management

Ubiquiti UniFi gear is a favorite for HomeLabs, but it comes with a catch. Unlike a standard consumer router, you cannot simply log into an Access Point’s IP address to change its SSID. These devices require a central brain: the UniFi Network Application. For years, Ubiquiti has pushed users toward the Cloud Key, a $200 proprietary dongle, or their own cloud-hosted portal.

Buying a Cloud Key adds another 13W power draw to your rack and introduces a single point of failure. These units are notorious for internal battery bloat and microSD card corruption. Relying on the cloud isn’t much better. It introduces latency and hands your private network topology over to a third-party server. If your internet drops, your ability to manage local hardware often vanishes with it.

Decoupling the software from the hardware solves this. By moving the UniFi controller into a Docker container, you reclaim your infrastructure. You save money, reduce clutter, and keep your data where it belongs: on your own disk.

Comparing Your Hosting Options

Choosing the right hosting method depends on your tolerance for maintenance and your budget. In a professional HomeLab, efficiency is everything. Docker consistently wins because it balances control with ease of use.

Why Docker is the Superior Choice

Docker isn’t just about saving $200. It changes how you manage the lifecycle of your network. If you decide to upgrade from a Raspberry Pi to a high-spec NUC, you don’t have to reconfigure your network. You just move your data volume and pull the image.

Version control is a lifesaver. Ubiquiti occasionally releases updates that break device adoption for older APs. With Docker, you can roll back to a previous image version in seconds. Backups are equally simple. Since all configurations live in a mapped folder, a single tar command or a scheduled script can back up your entire network state.

There are minor hurdles. You will need to manage port mappings and set up a database. Modern UniFi versions (7.5+) no longer bundle a database, requiring a separate MongoDB instance to function.

The Modern Stack: UniFi + MongoDB 7.0

The most stable architecture uses docker-compose to link the UniFi application with MongoDB. I recommend the LinuxServer.io images. They are updated frequently and handle file permissions much more gracefully than the official community builds.

Implementation Guide

1. Organize Your Files

Start by creating a clean directory structure. This prevents configuration files from scattering across your host system.

mkdir -p ~/unifi-stack/config
mkdir -p ~/unifi-stack/db
cd ~/unifi-stack

2. The Docker Compose Configuration

Create a docker-compose.yml file. This script defines the environment and opens the specific ports needed for L2 device discovery and the management interface.

version: "3.8"
services:
  unifi-db:
    image: mongo:7.0
    container_name: unifi-db
    volumes:
      - ./db:/data/db
      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro
    restart: unless-stopped

  unifi-network-application:
    image: lscr.io/linuxserver/unifi-network-application:latest
    container_name: unifi-network-application
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - MONGO_USER=unifi
      - MONGO_PASS=unifi-password
      - MONGO_HOST=unifi-db
      - MONGO_PORT=27017
      - MONGO_DBNAME=unifi
      - MEM_LIMIT=1024
    volumes:
      - ./config:/config
    ports:
      - 8443:8443 # Web Interface
      - 3478:3478/udp # STUN
      - 10001:10001/udp # Discovery
      - 8080:8080 # Device Inform
    restart: unless-stopped
    depends_on:
      - unifi-db

3. Automate Database Setup

UniFi requires a specific database user. Create init-mongo.js in your folder to handle this automatically on the first boot:

db.getSiblingDB('unifi').createUser({
  user: 'unifi',
  pwd: 'unifi-password',
  roles: [{ role: 'dbOwner', db: 'unifi' }, { role: 'dbOwner', db: 'unifi_stat' }]
});

4. Deploy the Stack

Fire up the containers in detached mode:

docker-compose up -d

Be patient. Java-based applications take time to warm up. It usually takes about 120 seconds for the web server to become responsive. You can watch the progress by running docker logs -f unifi-network-application.

Adopting Your Devices

Navigate to https://<your-ip>:8443. You will see a SSL warning; this is normal for self-hosted certificates. If your APs don’t show up immediately, they likely need a nudge. SSH into your AP (default login is ubnt/ubnt) and point it to your new controller manually:

set-inform http://<your-server-ip>:8080/inform

Final Maintenance Tips

Memory management is vital. For a typical home with three APs, 1GB of RAM is the sweet spot. If you notice the UI lagging, bump the MEM_LIMIT to 2048. Also, remember to choose the “Switch to Local User” option during the setup wizard. This bypasses the requirement for a UI.com account, ensuring your network remains accessible even if the internet goes dark.