Skip to content
Docker image and CLI management utility for Ubiquiti's UniFi Network Controller.
Python Dockerfile Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Docker UniFi Network Controller

Docker image and CLI management utility for a UniFi Network Controller for configuration and management of Ubiquiti wireless networking infrastructure.


  • Image components:
    • Ubuntu 18.04 base.
    • OpenJDK 8.
    • Ubiquiti Debian/Ubuntu Linux UniFi Network Controller.
    • MongoDB 3.4 for backend data store.
  • Controller by default bootstraps it's own MongoDB process, thus entire stack can be executed within a single Docker container.
  • Python CLI utility for start/stop of controller and handy backup/restore tasks.


To build an image with controller & MongoDB versions pinned to version:

$ ./

Alternatively, to pull a pre-built image from Docker Hub:

$ docker pull magnetikonline/unifi-network-controller:5.12.22

Images are tagged with their UniFi Network Controller release version.



To start the controller container:

$ docker run \
	--detach \
	--network host \
	--publish "8080:8080/tcp" \
	--publish "8443:8443/tcp" \
	--rm \

Published ports are for the following functions:

  • 8080: Device and controller communication.
  • 8443: Controller GUI/API.

Full list of local ingress ports used.

The --network host argument enables host networking:

  • Will (likely) ensure the controller can discover/communicate with the local network and allow devices to reach the controller.
  • Discards the need for published port (--publish) arguments, but won't hurt to still provide.

Once running the controller will present the initial welcome screen at

Adding persistent storage

You will probably want controller data stored on a persistent Docker volume, rather than within an ephemeral container:

# create volume - if not already exists
$ docker volume create "controller-data"

# start controller, mounting volume at /usr/lib/unifi/data
$ docker run \
	--detach \
	--mount "type=volume,src=controller-data,dst=/usr/lib/unifi/data" \
	--network host \
	--publish "8080:8080/tcp" \
	--publish "8443:8443/tcp" \
	--rm \

Or avoid all this boilerplate and use instead the Controller utility outlined below.

Controller utility

The CLI utility provides the following functions:

  • Start/stop the controller, using the version set in version. Will automatically create both data/log persistent Docker volumes if required.
  • Backup of the full data volume to a compressed tar archive.
  • Restore of an existing backup tar archive into a fresh Docker data volume.


$ ./ start --help
usage: start [-h] [--no-host-network]
                           [--server-prefix SERVER_PREFIX]

optional arguments:
  -h, --help            show this help message and exit
  --no-host-network     disable Docker host networking (may break ability to
                        locate local network devices)
  --server-prefix SERVER_PREFIX
                        prefix for controller container and associated mounted
                        volumes (default: unifi-network-controller)

# start the server
$ ./ start

Starting server [magnetikonline/unifi-network-controller:5.12.22] as [unifi-network-controller-server]
Running as container ID [ABCD...]

Note: if --server-prefix is used to set an alternative prefix for the server/controller and associated volumes it must be used with all related stop/backup/restore operations.


$ ./ stop

Stopping server [unifi-network-controller-server]
Server has stopped


The backup operation takes the full contents of the controller data Docker volume (MongoDB database, firmware downloads, miscellaneous config) and creates a compressed tar archive, which can be used for a full restore.

$ ./ backup --file "/path/to/backup.tgz"

Backup successfully created at [/path/to/backup.tgz]


Complementing the backup operation, restore takes an existing backup tar archive and extracts contents into a fresh Docker data volume.

Note: this will clobber any existing controller data volume which may exist - use with care.

$ ./ restore --file "/path/to/backup.tgz"

Removed existing data volume [unifi-network-controller-data]
Created volume [unifi-network-controller-data]
Data volume successfully restored from [/path/to/backup.tgz]
You can’t perform that action at this time.