magnetikonline/unifi-network-controller repository overview

⁠Docker UniFi Network Controller

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

• Overview⁠
• Building⁠
• Usage⁠
  • Basic⁠
  • Adding persistent storage⁠
• Controller utility⁠
  • Starting⁠
  • Stopping⁠
  • Backup⁠
  • Restore⁠
• Reference⁠

⁠Overview

• 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.

⁠Building

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

$ ./build.sh

Alternatively, pull the pre-built image from Docker Hub:

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

Images are tagged with their controller release version.

⁠Usage

⁠Basic

To start the controller container:

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

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 https://127.0.0.1:8443.

⁠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 \
	"magnetikonline/unifi-network-controller:5.14.23"

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

⁠Controller utility

The controller.py⁠ 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.

⁠Starting

$ ./controller.py start --help
usage: controller.py 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
$ ./controller.py start

Starting server [magnetikonline/unifi-network-controller:5.14.23] 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.

⁠Stopping

$ ./controller.py stop

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

⁠Backup

Takes full contents of the controller Docker data volume (including MongoDB database, firmware cache) and creates a compressed tar archive - which can then used for a restore⁠ operation.

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

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

⁠Restore

Complementing the backup operation, takes a given archive and extracts contents into a new Docker data volume.

Note: this will destroy an existing data volume - use with care.

$ ./controller.py 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]

⁠Reference

• How to Install & Upgrade the UniFi Network Controller⁠.