search

jacobalberty / unifi-docker

Unifi Docker files
MIT License
2.09k stars 448 forks source link

readme

Unifi-in-Docker (unifi-docker)

This repo contains a Dockerized version of Ubiqiti Network's Unifi Controller.

Why bother? Using Docker, you can stop worrying about version hassles and update notices for Unifi Controller, Java, or your OS. A Docker container wraps everything into one well-tested bundle.

To install, a couple lines on the command-line starts the container. To upgrade, just stop the old container, and start up the new. It's really that simple.

This container has been tested on Ubuntu, Debian, macOS, Windows, and even Raspberry Pi hardware.

Latest Version: The latest version is shown in the first line of the Current Information table on this page.

Setting up, Running, Stopping, Upgrading

First, install Docker on the "Docker host" - the machine that will run the Docker and Unifi Controller software. Use any of the guides on the internet to install on your Docker host. For Windows, see the Microsoft guide for installing Docker.

Then use the following steps to set up the directories and start the Docker container running.

Setting up directories

One-time setup: create the unifi directory on the Docker host. Within that directory, create two sub-directories: data and log.

cd # by default, use the home directory
mkdir -p unifi/data
mkdir -p unifi/log

Note: By default, this README assumes you will use the home directory on Linux, Unix, macOS. If you create the directory elsewhere, read the Options section below to adjust.)

Running Unifi-in-Docker

Each time you want to start Unifi, use this command. Each of the options is described below.

docker run -d --init \
   --restart=unless-stopped \
   -p 8080:8080 -p 8443:8443 -p 3478:3478/udp \
   -e TZ='Africa/Johannesburg' \
   -v ~/unifi:/unifi \
   --user unifi \
   --name unifi \
   jacobalberty/unifi

In a minute or two, (after Unifi Controller starts up) you can go to https://docker-host-address:8443 to complete configuration from the web (initial install) or resume using Unifi Controller.

Important: Two points to be aware of when you're setting up your Unifi Controller:

Stopping Unifi-in-Docker

To change options, stop the Docker container then re-run the docker run... command above with the new options. Note: The docker rm unifi command simply removes the "name" from the previous Docker image. No time-consuming rebuild is required.

docker stop unifi
docker rm unifi

Upgrading Unifi Controller

All the configuration and other files created by Unifi Controller are stored on the Docker host's local disk (~/unifi by default.) No information is retained within the container. An upgrade to a new version of Unifi Controller simply retrieves a new Docker container, which then re-uses the configuration from the local disk. The upgrade process is:

  1. MAKE A BACKUP on another computer, not the Docker host (Always, every time...)
  2. Stop the current container (see above)
  3. Enter docker run... with the newer container tag (see Current Information section below.)

Options on the Command Line

The options for the docker run... command are:

Current Information

The current tested version of unifi-docker is listed in the table below. You can choose the version of Unifi Controller in the docker run ... command. In Docker terminology, these versions are specified by "tags".

For example, in this project the container named jacobalberty/unifi (with no "tag") provides the most recent stable release. The table below lists recent versions.

The rc tag (for example, jacobalberty/unifi:rc) uses the most recent Release Candidate from the UniFi APT repository.

You may also specify a version number (e.g., jacobalberty/unifi:stable6) to get a specific version number, as shown in the table below.

Note: In Docker, specifying an image with no tag (e.g., jacobalberty/unifi) gets the "latest" tag. For Unifi-in-Docker, this uses the most recent stable version.

Tag Description Changelog
latest v8.2.93 Current Stable: Version 8.2.93 as of 2024-05-31 Change Log 8.2.93
rc Release Candidate: 7.2.92-rc as of 2022-07-29 Change Log 7.2.91-rc
stable-6 Final stable version 6 (6.5.55) Change Log 6.5.55
stable-5 Final stable version 5 (5.4.23) Change Log 5.14.23

multiarch

All available containers now support multiarch with amd64, armhf, and arm64 builds included. armhf for now uses mongodb 3.4, I do not see much of a path forward for armhf due to the lack of mongodb support for 32 bit arm, but I will support it as long as feasibly possible, for now that date seems to be expiration of support for ubuntu 18.04.

Adopting Access Points and Unifi Devices

Override "Inform Host" IP

For your Unifi devices to "find" the Unifi Controller running in Docker, you MUST override the Inform Host IP with the address of the Docker host computer. (By default, the Docker container usually gets the internal address 172.17.x.x while Unifi devices connect to the (external) address of the Docker host.) To do this:

See Side Projects for other techniques to get Unifi devices to adopt your new Unifi Controller.

Volumes

Unifi looks for the /unifi directory (within the container) for its special purpose subdirectories:

Legacy Volumes

These are no longer actually volumes, rather they exist for legacy compatibility. You are urged to move to the new volumes ASAP.

Environment Variables:

You can pass in environment variables using the -e option when you invoke docker run... See the TZ in the example above. Other environment variables:

Exposed Ports

The Unifi-in-Docker container exposes the following ports. A minimal Unifi Controller installation requires you expose the first three with the -p ... option.

See UniFi - Ports Used for more information.

Run as non-root User

The default container runs Unifi Controller as root. The recommended docker run... command above starts Unifi Controller so the image runs as unifi (non-root) user with the uid/gid 999/999. You can also set your data and logs directories to be owned by the proper gid.

Note: When you run as a non-root user, you will not be able to bind to lower ports by default. (This would not necessary if you are using the default ports.) If you must do this, also pass the --sysctl net.ipv4.ip_unprivileged_port_start=0 option on the docker run... to bind to whatever port you wish.

Certificate Support

To use custom SSL certs, you must map a volume with the certs to /unifi/cert

They should be named:

cert.pem  # The Certificate
privkey.pem # Private key for the cert
chain.pem # full cert chain

If your certificate or private key have different names, you can set the environment variables CERTNAME and CERT_PRIVATE_NAME to the name of your certificate/private key, e.g. CERTNAME=my-cert.pem and CERT_PRIVATE_NAME=my-privkey.pem.

For letsencrypt certs, we'll autodetect that and add the needed Identrust X3 CA Cert automatically. In case your letsencrypt cert is already the chained certificate, you can set the CERT_IS_CHAIN environment variable to true, e.g. CERT_IS_CHAIN=true. This option also works together with a custom CERTNAME.

Certificates Using Elliptic Curve Algorithms

If your certs use elliptic curve algorithms, which currently seems to be the default with letsencrypt certs, you might additionally have to set the UNIFI_ECC_CERT environment variable to true, otherwise clients will fail to establish a secure connection. For example an attempt with curl will show:

% curl -vvv https://my.server.com:8443
curl: (35) error:1404B410:SSL routines:ST_CONNECT:sslv3 alert handshake failure

You can check your certificate for this with the following command:

% openssl x509 -text < cert.pem | grep 'Public Key Algorithm'
         Public Key Algorithm: id-ecPublicKey

If the output contains id-ec as shown in the example, then your certificate might be affected.

Additional Information

This document describes everything you need to get Unifi-in-Docker running. The Side Projects and Background Info page provides more about what we've learned while developing Unifi-in-Docker.

TODO

This list is empty for now, please add your suggestions.