The deployment of enterprise-grade wireless management software within a containerized environment represents a significant shift in how network administrators handle high-density client deployments. The UniFi Controller software, now transitioning toward the UniFi Network Application nomenclature, serves as a powerful, enterprise wireless software engine. It is specifically engineered for environments requiring low latency and high uptime performance, ensuring that high-density client deployments do not suffer from management overhead or instability. Within the ecosystem provided by LinuxServer.io, these tools are packaged to ensure portability and consistency across different hardware architectures, leveraging Docker to abstract the underlying operating system dependencies.
The current state of these deployments is characterized by a critical transition. As of January 1, 2024, the original unifi-controller image has been deprecated. This means that while the image may still be available for legacy purposes, it no longer receives updates or official support. The industry standard has shifted toward the unifi-network-application image, which decouples the application logic from the database layer, typically utilizing a separate MongoDB container. This architectural shift improves scalability, simplifies backup procedures, and aligns with modern microservices principles where the application and the data store are treated as distinct entities.
Technical Specifications and Hardware Compatibility
The LinuxServer.io images are designed to be versatile, supporting multiple CPU architectures to ensure that they can run on everything from high-performance x86-64 servers to energy-efficient ARM-based devices.
The availability of these images is managed through specific tags. When a user pulls lscr.io/linuxserver/unifi-controller:latest, the Docker engine automatically attempts to retrieve the correct image for the host architecture. However, for those requiring explicit control or deploying in multi-arch environments, specific tags are available.
The following table outlines the architectural support for the controller images:
| Architecture | Availability | Specific Tag |
|---|---|---|
| x86-64 | Available | amd64-<version tag> |
| arm64 | Available | arm64v8-<version tag> |
| armhf | Not Available | N/A |
The lack of support for armhf indicates that the software requirements or the base image dependencies are not compatible with 32-bit ARM hardware. For those utilizing ARM64 (such as Raspberry Pi 4 or 5 running a 64-bit OS), the arm64v8 tag ensures optimal performance by utilizing the 64-bit instruction set.
Image Versioning and Tagging Strategy
Understanding the tagging system is crucial for maintaining a stable production environment. The LinuxServer.io team provides different tags to cater to different database requirements and stability needs.
latest: This tag points to the most recent stable releases of the UniFi Controller. It is intended for users who want the latest features and security patches.mongoless: This specific tag provides the UniFi Controller releases without the bundled MongoDB instance. This is critical for users who prefer to run their own managed database cluster or use a separate MongoDB container, allowing for better control over database tuning and backups.
Historically, an LTS (Long Term Support) tag existed; however, because Ubiquiti no longer releases LTS stable builds, this tag is no longer maintained. Users previously on the LTS path are encouraged to migrate to the latest tag. Technical testing has confirmed that a direct upgrade from version 5.6.42 (LTS) to 6.0.42 (latest) is successful, providing a viable path for legacy installations to modernize their controllers.
Detailed Deployment via Docker Compose
Docker Compose is the recommended method for deploying the UniFi Network Application. This approach allows for the definition of the entire stack—including environment variables, network ports, and volume mounts—within a single YAML file, ensuring reproducibility across different hosts.
For the current unifi-network-application deployment, the architecture requires a connection to a MongoDB instance. The following configuration demonstrates the required parameters:
yaml
services:
unifi-network-application:
image: lscr.io/linuxserver/unifi-network-application:latest
container_name: unifi-network-application
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- MONGO_USER=unifi
- MONGO_PASS=
- MONGO_HOST=unifi-db
- MONGO_PORT=27017
- MONGO_DBNAME=unifi
- MONGO_AUTHSOURCE=admin
- MEM_LIMIT=1024 #optional
- MEM_STARTUP=1024 #optional
- MONGO_TLS= #optional
volumes:
- /path/to/unifi-network-application/data:/config
ports:
- 8443:8443
- 3478:3478/udp
- 10001:10001/udp
- 8080:8080
- 1900:1900/udp #optional
- 8843:8843 #optional
- 8880:8880 #optional
- 6789:6789 #optional
- 5514:5514/udp #optional
restart: unless-stopped
The environment variables provided in this configuration serve critical roles:
PUIDandPGID: These variables allow the user to specify the Process User ID and Group ID. This is a fundamental feature of LinuxServer.io images to prevent permission mismatches between the host OS and the container. By mapping the container's internal user to a specific host user (determined by runningid your_user), the user ensures that files created in the/configvolume are owned by the correct account.TZ: This defines the timezone (e.g.,Etc/UTC), ensuring that system logs and scheduled backups reflect the correct local time.MONGO_variables: These define the connection string to the database.MONGO_HOSTrefers to the hostname of the database container (e.g.,unifi-db), whileMONGO_PORTtypically defaults to27017.MEM_LIMITandMEM_STARTUP: These optional parameters allow administrators to constrain the memory usage of the Java virtual machine (JVM), preventing the application from consuming all available system RAM on smaller hosts.
Legacy Deployment via Docker CLI
For users who prefer the command line or are testing a rapid deployment, the docker run command can be used. While functional, this method is less maintainable than Compose.
The legacy unifi-controller (all-in-one) deployment command is as follows:
bash
docker run -d \
--name=unifi-controller \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Etc/UTC \
-e MEM_LIMIT=1024 `#optional` \
-e MEM_STARTUP=1024 `#optional` \
-p 8443:8443 \
-p 3478:3478/udp \
-p 10001:10001/udp \
-p 8080:8080 \
-p 1900:1900/udp `#optional` \
-p 8843:8843 `#optional` \
-p 8880:8880 `#optional` \
-p 6789:6789 `#optional` \
-p 5514:5514/udp `#optional` \
-v /path/to/data:/config \
--restart unless-stopped \
lscr.io/linuxserver/unifi-controller:latest
For the newer unifi-network-application, the CLI command must include the MongoDB credentials:
bash
docker run -d \
--name=unifi-network-application \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Etc/UTC \
-e MONGO_USER=unifi \
-e MONGO_PASS= \
-e MONGO_HOST=unifi-db \
-e MONGO_PORT=27017 \
-e MONGO_DBNAME=unifi \
-e MONGO_AUTHSOURCE=admin \
-e MEM_LIMIT=1024 `#optional` \
-e MEM_STARTUP=1024 `#optional` \
-e MONGO_TLS= `#optional` \
-p 8443:8443 \
-p 3478:3478/udp \
-p 10001:10001/udp \
-p 8080:8080 \
-p 1900:1900/udp `#optional` \
-p 8843:8843 `#optional` \
-p 8880:8880 `#optional` \
-p 6789:6789 `#optional` \
-p 5514:5514/udp
Network Configuration and Port Mapping
A critical aspect of the UniFi deployment is the correct mapping of ports. Because the UniFi Controller communicates with Access Points (APs) and other hardware via specific protocols, these ports must be exposed to the host network.
The primary ports include:
8443: The Web User Interface. This is where the administrator accesses the dashboard viahttps://ip:8443.8080: The Inform port. This is the most critical port for device adoption, as APs use it to communicate their status to the controller.3478/udp: Used for STUN (Session Traversal Utilities for NAT), essential for device discovery and connectivity.10001/udp: Used for device discovery.
Optional ports include 1900/udp (UPnP), 8843, 8880, 6789, and 5514/udp (Syslog). Failure to open these ports will result in "disconnected" or "unable to manage" statuses for the connected UniFi hardware.
Device Adoption and Manual Configuration
When running UniFi inside a Docker container, the application is isolated from the physical network. By default, it uses an internal Docker IP address that is not accessible to the physical Access Points. This creates a challenge during the "adoption" phase, where the AP must be told where the controller resides.
To manually adopt a device, an administrator must use SSH to access the Access Point and manually set the inform URL.
The process follows these steps:
- Access the device via SSH:
ssh ubnt@$AP-IP - Set the inform target:
set-inform http://$address:8080/inform
In this context, $AP-IP is the current IP address of the Access Point, and $address is the IP address of the host machine running the Docker container. This overrides the default discovery mechanism and forces the AP to report directly to the containerized controller.
Troubleshooting Network and Security Issues
DHCP Gateway IP Failures
A known issue occurs when using a Security Gateway (router) where network-connected devices are unable to obtain an IP address. This typically stems from a mismatch in the gateway configuration within the software.
To resolve this, administrators must navigate to:
Settings > Networks > network_name
And set the "DHCP Gateway IP" to a correct and accessible IP address. This ensures that the DHCP requests are routed correctly through the gateway to the clients.
Reverse Proxy and SSL Certificates
By default, the LinuxServer UniFi images use self-signed certificates. This means the connection is encrypted via https, but it will be flagged as "untrusted" by most web browsers.
When integrating the container with a reverse proxy (such as Nginx, Traefik, or HAProxy), a common failure occurs if the proxy is configured to validate certificates. Because the internal certificate is self-signed, the proxy will reject the connection. To fix this, the "validate certificates" check must be disabled in the reverse proxy configuration for the specific UniFi container service.
Migration Strategies: Moving to the Network Application
As the unifi-controller image is deprecated, migration to the unifi-network-application image is mandatory for continued support and security.
Direct Migration for Mongoless Users
Users who were already using the mongoless tag for the old unifi-controller image have a streamlined path. Since the mongoless version already separated the database from the application, these users can switch directly to the unifi-network-application container without requiring additional migration steps.
Standard Migration Path (Backup and Restore)
For users of the all-in-one unifi-controller image, an in-place upgrade is not possible. The migration must be handled via a manual backup and restore process:
- Access the original UniFi-Controller web UI.
- Perform a full backup, ensuring the "include history" option is selected to preserve network logs and statistics.
- Shut down the old container completely to prevent data corruption.
- Start the new
unifi-network-applicationcontainer with a clean/configmount and a properly configured database container. - Use the setup wizard in the new installation to upload and restore the backup file.
Advanced Maintenance and Operations
Shell Access and Logging
For debugging purposes, administrators can enter the container's shell to inspect files or run internal commands:
docker exec -it unifi-network-application /bin/bash
To monitor the application's behavior and identify startup errors in real-time, use the log follow command:
docker logs -f unifi-network-application
Version Verification
To verify the exact build of the image being used, the following Docker inspect commands can be utilized:
To check the container version:
docker inspect -f '{{ index .Config.Labels "build_version" }}' unifi-network-application
To check the image version:
docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/unifi-network-application:latest
Update Philosophy
LinuxServer.io images are static and versioned. This means the application inside the container cannot be updated via a built-in "update" button. Instead, the image must be pulled anew and the container recreated.
The team strongly discourages the use of automated update tools that restart containers unattended. Instead, the use of Diun (Docker Image Update Notifier) is recommended. Diun notifies the administrator when a new image is available, allowing for a controlled manual update process.
Custom Build Procedures
For users who need to build the image from source or customize the base layers, the following workflow is utilized:
- Clone the repository:
git clone https://github.com/linuxserver/docker-unifi-controller.git - Enter the directory:
cd docker-unifi-controller - Build the image:
docker build --no-cache --pull -t lscr.io/linuxserver/unifi-controller:latest .
For those building on x86_64 hardware but targeting ARM, the multiarch/qemu-user-static tool must be registered:
docker run --rm --privileged multiarch/qemu-user-static:register --reset
Once registered, the ARM build can be initiated using the specific Dockerfile:
docker build -f Dockerfile.aarch64 .
Conclusion
The transition from the monolithic unifi-controller to the decoupled unifi-network-application reflects a broader shift toward modular infrastructure. By separating the application logic from the MongoDB database, LinuxServer.io has provided a more robust, maintainable, and scalable solution for managing UniFi networks. The success of this deployment relies on three critical pillars: correct PUID/PGID mapping for file permissions, precise port exposure for device communication, and a disciplined approach to updates and migrations. While the manual adoption process and reverse proxy certificate issues present initial hurdles, the resulting environment provides the low latency and high uptime required for enterprise-level wireless management.