🕸 No longer maintained! 🕸
Docker image to run UniFi Controller (aka UniFi Network Application) on Raspberry Pi Zero.
You can pull the image from Docker Hub:
docker pull chopeen/unifi-docker-raspi:latestThis repository is a fork of jacobalberty/unifi-docker, with some additional ideas taken from jcberthon/unifi-docker and a blog post by Tyson Nichols.
export UNIFI_DIR=~/unifi/
# create a directory to persist UniFi data outside the container
mkdir $UNIFI_DIR
# set the directory to be owned by "unifi" user
sudo chown -R 999:999 $UNIFI_DIRexport UNIFI_DIR=~/unifi/
# (optional) stop the running container and rename it
docker container stop unifi_raspi
docker rename unifi_raspi unifi_raspi_old
# start the container
docker run \
-d \
--restart=unless-stopped \
--init \
-p 8080:8080 -p 8443:8443 -p 3478:3478/udp -p 10001:10001/udp \
--volume $UNIFI_DIR:/unifi \
-e TZ='Europe/Warsaw' \
-e JVM_MAX_HEAP_SIZE='512m' \
--memory 350m \
--user unifi \
--name unifi_raspi \
chopeen/unifi-docker-raspi:latestFor explanation of the docker run arguments used above, see:
- UniFi Controller With Raspberry Pi And Docker
- jcberthon/unifi-docker # Running the container on low-memory devices
- jacobalberty/unifi-docker # Run as non-root User
đź“ť TODO: Research the warning Your kernel does not support memory limit capabilities or the cgroup is not mounted. Limitation discarded.
The image was tested with Raspberry Pi Zero W (2017).
Zero W specs
$ cat /proc/cpuinfo
processor : 0
model name : ARMv6-compatible processor rev 7 (v6l)
BogoMIPS : 697.95
Features : half thumb fastmult vfp edsp java tls
CPU implementer : 0x41
CPU architecture: 7
CPU variant : 0x0
CPU part : 0xb76
CPU revision : 7
Hardware : BCM2835
Revision : 19000c1
Serial : 00000000b8d1df6c
Model : Raspberry Pi Zero W Rev 1.1# logs
less ~/unifi/log/server.log
less ~/unifi/log/mongod.log
docker logs unifi_raspi
# access the container's shell
docker exec -it unifi_raspi /bin/bash
# restart the container
docker restart unifi_raspi🕸️ This instruction is now obsolete.
đź’ˇ If you provide your DOCKERHUB_USERNAME and DOCKERHUB_TOKEN in repository secrets
and change DOCKER_IMAGE value to point a repository in your account, the "Publish Docker image"
workflow (see docker.yml) will publish the image to Docker Hub automatically.
The base images were changed to:
navikey/raspbian-busterbalenalib/raspberry-pi-golang:1-buster-build(there is also Zero-specific orange-pi-zero-golang - would it be better?)
so that it is possible to run the build on Raspberry Pi Zero.
# set up Docker
curl -fsSL https://get.docker.com -o docker.sh
sh docker.sh
# (optional) to run `docker` command without `sudo`; restart the session afterwards
sudo usermod -aG docker pi
# set up the Buildx plugin
mkdir ~/.docker/cli-plugins/
curl -L "https://github.com/docker/buildx/releases/download/v0.7.1/buildx-v0.7.1.linux-arm-v6" > ~/.docker/cli-plugins/docker-buildx
chmod a+x ~/.docker/cli-plugins/docker-buildx
# clone the repository
git clone https://github.com/chopeen/unifi-docker-raspi.git
cd unifi-docker-raspi/# (optional) log in to Docker Hub, to avoid random errors when pulling base images
docker login
# build the image for appropriate platform
export UNIFI_REPOSITORY=chopeen/unifi-docker-raspi
docker buildx build --platform linux/arm/v6 -t ${UNIFI_REPOSITORY}:latest .
# tag the image with Controller version number
export UNIFI_VERSION=6.5.55
docker image tag ${UNIFI_REPOSITORY}:latest ${UNIFI_REPOSITORY}:${UNIFI_VERSION}
# publish the image to Docker Hub
docker push ${UNIFI_REPOSITORY}:latest
docker push ${UNIFI_REPOSITORY}:${UNIFI_VERSION}Running the build on Zero W (2017) takes about an hour, so be patient.
Expected output
$ docker buildx build --platform linux/arm/v6 -t chopeen/unifi-docker-raspi:latest .
[+] Building 3581.6s (19/20)
[+] Building 3784.3s (20/20) FINISHED
=> [internal] load build definition from Dockerfile 3.5s
=> => transferring dockerfile: 2.76kB 1.5s
=> [internal] load .dockerignore 1.8s
=> => transferring context: 2B 0.1s
=> [internal] load metadata for docker.io/navikey/raspbian-buster:latest 14.0s
=> [internal] load build context 2.3s
=> => transferring context: 16.55kB 0.4s
=> [ 1/15] FROM docker.io/navikey/raspbian-buster:latest@sha256:ae129c1204bdf26713d125c7092ae33f6d6cd597d9bf660952b1ea8bbc3d708d 574.7s
=> => resolve docker.io/navikey/raspbian-buster:latest@sha256:ae129c1204bdf26713d125c7092ae33f6d6cd597d9bf660952b1ea8bbc3d708d 3.1s
=> => sha256:ae129c1204bdf26713d125c7092ae33f6d6cd597d9bf660952b1ea8bbc3d708d 1.41kB / 1.41kB 0.0s
=> => sha256:afec9605c25178c20b3c637ec79b948617b2dd90a40cfb458a2c6d3821432e12 528B / 528B 0.0s
=> => sha256:f3051d5b3cafd34c223454a25f92c673441de3c0ae7d978835f8f69b6107ddd9 706B / 706B 0.0s
=> => sha256:2764edd039a4cf5f888ce940db1021b4f01e2f74ba952d584c6139d7b5f507e6 90.45MB / 90.45MB 103.0s
=> => extracting sha256:2764edd039a4cf5f888ce940db1021b4f01e2f74ba952d584c6139d7b5f507e6 408.7s
=> [ 2/15] RUN set -eux; apt-get update; apt-get install -y gosu; rm -rf /var/lib/apt/lists/* 226.9s
=> [ 3/15] RUN mkdir -p /usr/unifi /usr/local/unifi/init.d /usr/unifi/init.d /usr/local/docker 24.1s
=> [ 4/15] COPY docker-entrypoint.sh /usr/local/bin/ 21.8s
=> [ 5/15] COPY docker-healthcheck.sh /usr/local/bin/ 19.1s
=> [ 6/15] COPY docker-build.sh /usr/local/bin/ 12.7s
=> [ 7/15] COPY functions /usr/unifi/functions 12.2s
=> [ 8/15] COPY import_cert /usr/unifi/init.d/ 12.7s
=> [ 9/15] COPY pre_build /usr/local/docker/pre_build 13.3s
=> [10/15] RUN chmod +x /usr/local/bin/docker-entrypoint.sh && chmod +x /usr/unifi/init.d/import_cert && chmod +x /usr/local/bin/docker-healthcheck.sh && chmod 24.3s
=> [11/15] RUN set -ex && mkdir -p /usr/share/man/man1/ && groupadd -r unifi -g 999 && useradd --no-log-init -r -u 999 -g 999 unifi && /usr/local/bin/docker- 2335.0s
=> [12/15] RUN mkdir -p /unifi && chown unifi:unifi -R /unifi 26.6s
=> [13/15] COPY hotfixes /usr/local/unifi/hotfixes 12.7s
=> [14/15] RUN chmod +x /usr/local/unifi/hotfixes/* && run-parts /usr/local/unifi/hotfixes 49.4s
=> [15/15] WORKDIR /unifi 11.0s
=> exporting to image 372.9s
=> => exporting layers 372.8s
=> => writing image sha256:475df499fbb7a30cb7b1c7d23d332a391047b9f0c42bc20153164af5aa4e7e4c 0.1s
=> => naming to docker.io/chopeen/unifi-docker-raspi:latest đź“ť TODO: Research how to perform this build on Ubuntu (Getting started with Docker for Arm on Linux)
When I tried to use the original jacobalberty/unifi-docker image from Docker Hub on Raspberry Pi Zero, it failed with error:
The requested image's platform (linux/arm/v7) does not match the detected host platform (linux/arm/v6) and no specific platform was requested
The supported platforms are: linux/amd64, linux/arm/v7 and linux/arm64.
I tried building a new image from the original Dockerfile with --platform linux/arm/v6,
but - depending on the machine (Ubuntu laptop or Raspberry Pi) - it failed with different errors:
=> ERROR [internal] load metadata for docker.io/library/ubuntu:18.04 0.3s
------
> [internal] load metadata for docker.io/library/ubuntu:18.04:
------
error: failed to solve: failed to solve with frontend dockerfile.v0: failed to create LLB definition: no match for platform in manifest sha256:0fedbd5bd9fb72089c7bbca476949e10593cebed9b1fb9edf5b79dbbacddd7d6: not found => ERROR [ 2/15] RUN set -eux; apt-get update; apt-get install -y gosu; rm -rf /var/lib/apt/lists/* 0.9s
------
> [ 2/15] RUN set -eux; apt-get update; apt-get install -y gosu; rm -rf /var/lib/apt/lists/*:
#5 0.599 standard_init_linux.go:228: exec user process caused: exec format error
------
error: failed to solve: executor failed running [/bin/sh -c set -eux; apt-get update; apt-get install -y gosu; rm -rf /var/lib/apt/lists/*]: exit code: 1The goal is to publish a Docker image with UniFi Controller for Raspberry Pi Zero as well as provide some advice for running it on low-memory devices.
[original README below]
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.
See the Current Information section for the latest versions.
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.
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/logNote: 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.)
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/unifiIn 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:
- When your browser initially connects to the link above, you will see a warning about an untrusted certificate. If you are certain that you have typed the address of the Docker host correctly, agree to the connection.
- See the note below about Override "Inform Host" IP so your Unifi devices can "find" the Unifi Controller.
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 unifiAll 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:
- MAKE A BACKUP on another computer, not the Docker host (Always, every time...)
- Stop the current container (see above)
- Enter
docker run...with the newer container tag (see Current Information section below.)
The options for the docker run... command are:
-d- Detached mode: Unifi-in-Docker runs in the background--init- Recommended to ensure processes get reaped when they die--restart=unless-stopped- If the container should stop for some reason, restart it unless you issue adocker stop ...-p ...- Set the ports to pass through to the container.-p 8080:8080 -p 8443:8443 -p 3478:3478/udpis the minimal set for a working Unifi Controller.-e TZ=...Set an environment variable namedTZwith the desired time zone. Find your time zone in this list of timezones.-e ...See the Environment Variables section for more environment variables.-v ...- Bind the volume~/unifion the Docker host to the directory/unifiinside the container. These instructions assume you placed the "unifi" directory in your home directory. If you created the directory elsewhere, modify the~/unifipart of this option to match. See the Volumes discussion for other volumes used by Unifi Controller.--user unifi- Run as a non-root user. See the Run as non-root User discussion belowjacobalberty/unifi- the name of the container to use. Thejacobalberty...image is retrieved from Dockerhub. The Current Information section below discusses the versions/tags that are available.
The current "latest" version is Unifi Controller 7.3.83. There are currently no hot-fix or CVE warnings affecting Unifi Controller.
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 v7.3.83 |
Current Stable: Version 7.3.83 as of 2023-02-08 | Change Log 7.3.83 |
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 |
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.
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:
- Find Settings -> System -> Other Configuration -> Override Inform Host: in the Unifi Controller web GUI. (It's near the bottom of that page.)
- Check the "Enable" box, and enter the IP address of the Docker host machine.
- Save settings in Unifi Controller
- Restart UniFi-in-Docker container with
docker stop ...anddocker run ...commands.
See Side Projects for other techniques to get Unifi devices to adopt your new Unifi Controller.
Unifi looks for the /unifi directory (within the container)
for its special purpose subdirectories:
-
/unifi/dataThis contains your UniFi configuration data. (formerly:/var/lib/unifi) -
/unifi/logThis contains UniFi log files (formerly:/var/log/unifi) -
/unifi/certPlace custom SSL certs in this directory. For more information regarding the naming of the certificates, see Certificate Support. (formerly:/var/cert/unifi) -
/unifi/init.dYou can place scripts you want to launch every time the container starts in here -
/var/run/unifiRun information, in general you will not need to touch this volume. It is there to ensure UniFi has a place to write its PID files
These are no longer actually volumes, rather they exist for legacy compatibility. You are urged to move to the new volumes ASAP.
/var/lib/unifiNew name:/unifi/data/var/log/unifiNew name:/unifi/log
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:
-
UNIFI_HTTP_PORTThis is the HTTP port used by the Web interface. Browsers will be redirected to theUNIFI_HTTPS_PORT. Default: 8080 -
UNIFI_HTTPS_PORTThis is the HTTPS port used by the Web interface. Default: 8443 -
PORTAL_HTTP_PORTPort used for HTTP portal redirection. Default: 80 -
PORTAL_HTTPS_PORTPort used for HTTPS portal redirection. Default: 8843 -
UNIFI_STDOUTController outputs logs to stdout in addition to server.log Default: unset -
TZTimeZone. (i.e America/Chicago) -
JVM_MAX_THREAD_STACK_SIZEUsed to set max thread stack size for the JVM Example:--env JVM_MAX_THREAD_STACK_SIZE=1280k -
LOTSOFDEVICESEnable this withtrueif you run a system with a lot of devices and/or with a low powered system (like a Raspberry Pi). This makes a few adjustments to try and improve performance:- enable unifi.G1GC.enabled
- set unifi.xms to JVM_INIT_HEAP_SIZE
- set unifi.xmx to JVM_MAX_HEAP_SIZE
- enable unifi.db.nojournal
- set unifi.dg.extraargs to --quiet
See the Unifi support site for an explanation of some of those options. Default: unset
-
JVM_EXTRA_OPTSUsed to start the JVM with additional arguments. Default: unset -
JVM_INIT_HEAP_SIZESet the starting size of the javascript engine for example:1024MDefault: unset -
JVM_MAX_HEAP_SIZEJava Virtual Machine (JVM) allocates available memory. For larger installations a larger value is recommended. For memory constrained system this value can be lowered. Default: 1024M
The Unifi-in-Docker container exposes the following ports.
A minimal Unifi Controller installation requires you
expose the first three with the -p ... option.
- 8080/tcp - Device command/control
- 8443/tcp - Web interface + API
- 3478/udp - STUN service
- 8843/tcp - HTTPS portal (optional)
- 8880/tcp - HTTP portal (optional)
- 6789/tcp - Speed Test (unifi5 only) (optional)
See UniFi - Ports Used for more information.
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.
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 chainIf 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.
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.
This list is empty for now, please add your suggestions.