Mastering Docker on Synology NAS: From Remote CLI Orchestration to Automated Lifecycle Management

The integration of Docker into the Synology DiskStation Manager (DSM) ecosystem has transformed the traditional Network Attached Storage (NAS) device from a simple file repository into a potent, multi-service container server. For the modern technical enthusiast, the appeal of Docker lies in the concept of "disposable workspaces." This architectural shift allows for the deployment of services and applications that can be instantly reified—brought into existence—and subsequently removed without leaving residual artifacts or "configuration drift" on the host operating system. While Synology provides a polished graphical user interface (GUI) via the Container Manager, the true power of the platform is unlocked when the administrator moves beyond the GUI and leverages the Docker Command Line Interface (CLI) for remote orchestration and automated maintenance tools like Watchtower.

The Architectural Evolution of Synology Containerization

Synology's implementation of Docker allows users to run isolated environments that share the host's kernel but remain decoupled from the underlying DSM system files. This separation is critical for stability; a failure within a container does not jeopardize the integrity of the NAS's core operating system. The transition from a simple GUI-based approach to a CLI-driven workflow is often motivated by the desire for a more fluid development experience, especially for those accustomed to Unix-style environments.

The ability to separate the Docker client (the tool used to issue commands) from the Docker engine (the service that manages the containers) is a fundamental strength of the Docker architecture. On a Synology NAS, this allows an administrator to control the NAS's container resources from a remote workstation, effectively turning the NAS into a headless Docker host.

Advanced Remote Access Configuration for Docker

By default, the Docker installation on a Synology NAS restricts the use of the CLI to users with root privileges. When accessing the NAS via Secure Shell (SSH), a standard administrator account cannot execute Docker commands without the use of sudo.

Transitioning to Non-Root User Execution

To achieve a seamless workflow, it is necessary to allow non-root users to interact with the Docker daemon. In a standard Linux environment, this is typically handled by adding the user to the docker group. For Synology users, this eliminates the need to repeatedly enter passwords for sudo and allows for the direct invocation of the Docker CLI.

The technical requirement involves modifying the user permissions to align with the standard Docker post-installation steps for Linux. Once the administrator user is granted these permissions, the remote invocation of Docker commands via SSH becomes possible. An example of the version check after this configuration is:

ssh ds1621plus docker -v

This command verifies the connectivity and the version of the Docker engine running on the NAS, such as version 20.10.3 build b35e731.

Implementing Docker Contexts for Remote Orchestration

While SSH commands are functional, the use of "Docker Contexts" provides a superior method of management. A context is essentially a named configuration that tells the local Docker CLI which engine to communicate with. Instead of manually wrapping every command in an SSH call, the administrator can switch the local environment to point directly to the Synology NAS.

The process of creating a remote context involves the following command:

bash docker context create --docker host=ssh://administrator@ds1621plus --description="Synology NAS" synology

After creating the context, the administrator must list the available contexts to ensure the new target is recognized:

bash docker context list

The output of this command will show the default context (pointing to the local machine's Unix socket) and the new synology context pointing to the SSH endpoint of the NAS. To activate the remote target, the following command is used:

bash docker context use synology

Once the context is active, any subsequent Docker command—such as docker image ls—is executed on the local machine's terminal but is processed by the Docker engine on the Synology NAS. This removes the abstraction layer of the SSH shell and treats the NAS as a remote node in the user's local development environment.

Automated Lifecycle Management with Watchtower

Maintaining containers manually can be time-consuming and prone to human error. Watchtower is a specialized tool designed to monitor running containers and automatically update them to the latest versions available on the registry.

The Role of Watchtower in the Synology Ecosystem

Watchtower solves a specific limitation of the Synology Container Manager GUI. While the GUI can alert users to updates for images hosted on Docker Hub, it lacks the visibility to detect updates for images hosted on other repositories, such as GitHub. Watchtower extends this capability, allowing for the automatic pulling of updated images and the subsequent restart of the container to apply the new version.

Due to the fact that Synology often utilizes older versions of the Docker engine compared to the absolute bleeding edge of the industry, certain compatibility flags are required. The currently maintained fork of the project, nicholas-fedor/watchtower, includes specific environment variables to ensure compatibility with the older Docker versions found in DSM.

Deploying Watchtower via Container Manager Projects

The most efficient way to deploy Watchtower on DSM is through the "Project" functionality in Container Manager, which utilizes Docker Compose files. This method ensures that the configuration is version-controlled and easily reproducible.

The initial setup requires a dedicated directory structure for the project files:

/docker/projects/watchtower-compose

The deployment utilizes a YAML-based compose file. Below is the technical specification for a robust Watchtower deployment:

yaml services: watchtower: image: nickfedor/watchtower:latest container_name: watchtower environment: - TZ=YOURTIMEZONE - WATCHTOWER_CLEANUP=true - WATCHTOWER_INCLUDE_STOPPED=true - WATCHTOWER_REVIVE_STOPPED=false - WATCHTOWER_SCHEDULE=0 0 2 * * * - DOCKER_API_VERSION="1.43" command: - overseerr - plex - prowlarr - radarr - sonarr - tautulli - watchtower volumes: - /var/run/docker.sock:/var/run/docker.sock restart: unless-stopped

Technical Analysis of Watchtower Configuration

The configuration above contains several critical parameters that impact the stability and storage efficiency of the NAS:

• The DOCKER_API_VERSION="1.43" variable is mandatory for compatibility with Synology's specific Docker implementation.
• The volume mapping /var/run/docker.sock:/var/run/docker.sock is the most critical component; it allows Watchtower to communicate with the Docker API to stop, start, and update other containers.
• The command section explicitly lists the containers that Watchtower is permitted to update, providing a layer of safety by preventing the automatic update of sensitive services that might require manual migration.

Detailed Environment Variable Matrix

Operational Considerations and Troubleshooting

When using Watchtower on a Synology NAS, users may encounter specific behavioral anomalies related to the DSM notification system. Because Watchtower performs the update process by stopping the container, pulling the new image, and restarting the service, the Synology Container Manager may perceive the initial stop as an unexpected failure. Consequently, DSM may trigger an alert stating that a container "stopped unexpectedly." This is a benign side effect of the automation and does not indicate a system fault.

Alternative Update Strategies

For users who prefer more granular control over their updates, there are two primary methods of managing Watchtower's scope:

1. Inclusion List: Specifying the exact names of containers in the command section of the compose file.
2. Exclusion Labels: Using labels to tell Watchtower to ignore specific containers. For example, adding the following label to a container will prevent Watchtower from touching it:

yaml labels: - com.centurylinklabs.watchtower.enable=false

This label-based approach is generally more efficient for large-scale deployments where most containers should be updated, but a few critical ones must remain on a specific version to avoid breaking changes.

DSM Compatibility Matrix

The versatility of Docker on Synology is evidenced by its broad compatibility across various versions of DiskStation Manager. The following table outlines the supported versions for current Docker guides and implementations:

Conclusion

The transformation of a Synology NAS into a professional-grade Docker host requires a transition from the simplistic GUI to a more sophisticated, CLI-centric management strategy. By implementing remote access through non-root user permissions and the creation of Docker contexts, administrators can eliminate the friction of SSH-wrapped commands and manage their infrastructure from any compatible machine. Furthermore, the deployment of Watchtower—specifically the nicholas-fedor fork—ensures that the system remains current without requiring manual intervention, provided that the DOCKER_API_VERSION is correctly set to maintain compatibility with DSM's backend. The intersection of these technologies allows for a highly resilient, automated, and scalable home lab or business server environment, where the primary focus shifts from the maintenance of the platform to the utility of the services running upon it.

Sources

1. Remote access to Docker on my Synology NAS
2. mariushosting Docker Guides
3. Watchtower Automated Updates in Container Manager