Architecting a Ubiquiti UniFi Network Application Environment on Synology NAS

The UniFi Network Application, frequently referred to as the UniFi Controller, serves as the centralized management hub for Ubiquiti Networks' wireless ecosystem. This software solution transforms the way network administrators interact with their hardware, shifting the paradigm from individual device configuration to a unified, web-browser-based management interface. By deploying this application on a Synology Network Attached Storage (NAS) device, users can achieve a persistent, self-hosted management layer that eliminates the need for a dedicated hardware Cloud Key or a 24/7 powered-on PC. This integration leverages the virtualization capabilities of Docker (now often branded as Container Manager in newer DSM versions), allowing the controller to run in an isolated environment while maintaining direct access to the host's network resources.

The deployment of UniFi Controller version 7.5.176 on a Synology NAS is a strategic move for both home enthusiasts and professional IT administrators. It centralizes the control plane for multiple wireless networks, enabling the orchestration of access points, switches, and gateways from a single pane of glass. However, achieving a stable installation requires precise attention to file system permissions, network port forwarding, and container resource allocation. The process involves utilizing the Synology Task Scheduler to execute a specific Docker run command, which bypasses the need for manual terminal entry, making the deployment accessible to users who are uncomfortable with Command Line Interfaces (CLI).

Hardware Requirements and Compatibility Analysis

Before initiating the installation, it is critical to analyze the underlying hardware of the Synology NAS to ensure the environment can support the UniFi Network Application's resource demands.

The hardware capabilities vary significantly across the Synology lineup. For instance, the DS120j is a budget-friendly model that supports the installation of the Container Manager (Docker). While it is listed as compatible, it possesses only 512 MB of RAM. In contrast, higher-end models like the RS815+ or DS220+ offer significantly more headroom. Real-world testing on an RS815+ with only 2 GB of RAM demonstrates that the UniFi Controller consumes approximately 802 MB of memory with minimal CPU overhead.

The impact of using a low-memory device like the DS120j is a potential risk of container instability or slow performance during the initial boot sequence and database migrations. While the software may install, the limited RAM might lead to "Out of Memory" (OOM) errors during heavy network polling or when managing a large number of devices. Therefore, while the DS120j is technically capable of running the container, a device with at least 2 GB of RAM, such as the DS220+, is a superior choice for long-term stability.

Pre-Installation Environment Preparation

The foundation of a successful Docker deployment on Synology is the correct organization of persistent data. Because Docker containers are ephemeral—meaning any data inside the container is lost when the container is updated or deleted—it is mandatory to map a local folder on the NAS to the container's configuration directory.

The first operational step is to utilize the File Station application within the Synology DSM interface. Within the shared folder named docker, a new subfolder must be created.

• Folder name: unifi

It is imperative that this folder name is entered using only lowercase letters. The use of uppercase letters can lead to pathing errors within the Linux-based environment of the Docker container, potentially causing the application to fail to load its configuration files or resulting in a "Permission Denied" error during the boot sequence. This folder serves as the /config volume, ensuring that all network settings, device adoption data, and historical logs are stored on the NAS physical disks rather than within the virtual container layer.

Automated Deployment via Task Scheduler

To avoid the complexity of the SSH terminal, the installation can be executed through the Synology Task Scheduler. This method allows the administrator to run a docker run command as the root user, ensuring the container has the necessary privileges to bind to the required network ports.

The process begins in the Control Panel under the Task Scheduler menu. The administrator must create a new User-defined script.

The configuration of this task is broken down into three specific sections:

1. General Settings: The task should be named Install Unifi Controller 7. Crucially, the "Enabled" option must be unchecked initially to prevent the script from running before the configuration is finalized. The user account must be set to root to ensure the Docker engine has the authority to create the container and manage network interfaces.

2. Schedule: The setting must be changed to "Run on the following date" with "Do not repeat" selected. This ensures the script acts as a one-time installer rather than a recurring task.

3. Task Settings: The "Send run details by email" option should be enabled to provide the administrator with a log of the installation outcome.

The core of the installation is the script pasted into the "Run command" area. The following command is utilized:

bash docker run -d --name=Unifi-Controller-7 \ -p 3478:3478/udp \ -p 10001:10001/udp \ -p 5514:5514/udp \ -p 8080:8080 \ -p 8443:8443 \ -p 8880:8880 \ -p 8843:8843 \ -e PUID=1026 \ -e PGID=100 \ -e TZ=Europe/Bucharest \ -v /volume1/docker/unifi:/config \ --restart always \ ghcr.io/linuxserver/unifi-controller

This command performs several critical functions:

• The -d flag runs the container in detached mode, allowing it to operate in the background.
• The --name flag assigns a unique identifier to the container for easy management.
• The -p flags map the internal container ports to the NAS host ports. This is essential for device discovery and management.
• The -e flags set environment variables. The PUID and PGID must be modified to match the specific User ID and Group ID of the Synology user to avoid permission issues with the /config folder. The TZ (Time Zone) must be updated to the user's specific region (e.g., America/New_York) to ensure logs and scheduled backups reflect the correct time.
• The -v flag links the previously created /volume1/docker/unifi folder to the internal /config directory.
• The --restart always flag ensures that the controller starts automatically if the NAS reboots or the container crashes.
• The image is pulled from the LinuxServer.io GitHub Container Registry (ghcr.io), which is known for providing highly optimized and frequently updated images for the UniFi community.

Post-Installation Activation and Web Interface Access

After executing the script, the system requires a grace period. The installation process and the initial database creation can take several minutes. Attempting to access the interface immediately often results in a blank 400 error page or a 404 Not Found error. Users are advised to wait approximately 2 to 3 minutes.

Access to the UniFi Network Application is achieved via a web browser. The URL structure is as follows:

http://[Synology-IP-Address]:8080

Upon successful loading, the user is presented with the installation wizard. This requires the selection of a controller name and the acceptance of the user license and terms of service.

If the user encounters connectivity issues, there are three primary troubleshooting vectors:

1. Port Conflict: While port 8080 is the primary management port, some users may find that port 8443 is required for HTTPS access. If 8080 returns a 404 error, testing 8443 is a viable alternative.
2. Firewall Rules: The Synology Firewall must be configured to allow traffic on the ports defined in the Docker run command. Specifically, Rule 6 on the Synology Firewall must be correctly set up to permit these ports, otherwise, the NAS will drop incoming packets from the UniFi devices.
3. Network Mode: In some DSM versions (7.1 or 7.2), users may notice the absence of the "use same network as docker host" option in the Container Manager GUI. Using the Task Scheduler script bypasses this limitation by explicitly mapping the ports, but it is a known point of confusion for those attempting manual GUI installation.

Device Adoption and Network Optimization

Once the interface is accessible, the administrator must integrate the physical UniFi hardware. Devices (Access Points, Switches) will appear in the device list once they find the controller on the network.

The adoption process involves the following steps:

• Locate the device in the list.
• Select "Click to Adopt".
• A side window will appear; click "Adopt Device".
• Wait for the status to transition from "Pending" to "Online".

A critical optimization step for the UniFi Network Application on a NAS is the "Override Inform Host" setting. By default, UniFi devices may attempt to communicate with the controller using an internal Docker IP address, which is not routable by the physical devices on the network.

To fix this:
1. Navigate to Settings.
2. Go to System.
3. Scroll to the bottom of the page.
4. Enable "Override inform host".
5. Enter the static IP address of the Synology NAS.

This ensures that the devices always know the correct IP address of the controller, preventing devices from showing as "Disconnected" or "Managed by Other" after a reboot.

Technical Specifications and Port Mapping Table

For a complete understanding of the network traffic flowing to the Synology NAS, the following table details the ports used by the UniFi Controller 7 container.

Conclusion

The deployment of the UniFi Network Application 7 on a Synology NAS represents a sophisticated marriage of network management software and virtualization. By utilizing a Docker-based approach via the Task Scheduler, administrators can bypass the limitations of the GUI and the complexities of the CLI, resulting in a deployment that can be completed in under 30 seconds of execution time. However, the long-term success of this installation depends on the alignment of three factors: hardware resource availability (specifically RAM), accurate PUID/PGID environment variables for file system permissions, and the correct configuration of the "Override Inform Host" setting to maintain device connectivity.

While the DS120j can technically host the application, the resource-heavy nature of the UniFi database suggests that a model with 2 GB of RAM or more is the optimal choice for production environments. The use of the LinuxServer.io image ensures a level of standardization and stability, provided that the Synology Firewall is opened to the necessary UDP and TCP ports. This architecture provides a robust, scalable, and cost-effective alternative to proprietary hardware controllers, granting the user full control over their data and the update cycle of their network management plane.

Sources

1. Marius Hosting - How to Install Unifi Controller 7 on Your Synology NAS
2. Spiceworks Community - UniFi Controller for Synology NAS