How to use Docker on a Synology NAS

Today we are going to look at how to use Docker on a Synology NAS.

The majority of the explanation will be done through the video above, but it’s important to have certain points documented. The Docker implementation on a Synology NAS is very powerful when you understand it, but it’s slightly confusing when you initially get started. While I create specific tutorials that will guide you through the implementation of specific containers, my goal is to give you the knowledge needed to implement whatever container you’d like.

DOCKER HAS BEEN UPDATED TO A NEW USER INTERFACE! The settings are the exact same, though they’re in different locations. The video below shows the differences between the old and new UI so that you can utilize tutorials in their current format and understand where to add all of the settings!

1. Volume Mounting – How to Use Synology NAS Docker

When creating a Docker container, the important data must be mapped to a local folder. This is completed in the Volume section, where a local folder is mapped to a container folder. When the container runs, the container’s folder location in the Mount Path below is written to the File/Folder entered on your Synology NAS. Any data that is modified on the local Synology NAS folder will write to the containers folder.

It’s important to highlight that you can’t mount any folders that you’d like. When you download an image from the registry, a little icon (shown below) will bring you to the documentation for that container. You can search that documentation to see what folders can be mounted.

After you navigate to the documentation, you will have to search the page to see what volumes can be mounted. Unfortunately, all documentation is different, so you will have to search through it to find the volume information. Using Pi-Hole as an example, an example Docker Compose file is provided. Under the volumes section, you can find the two volumes that can be mounted.

Using ./etc-pihole/:/etc/pihole/ as an example, etc-pihole is the local folder and /etc/pihole is the container’s folder. You can easily translate this to a Synology NAS by creating subfolders in the docker folder and mounting that folder location to the container’s folder. Using the screenshot below, I created a folder named pi-hole and a sub-folder name etc-pihole.

Those folders are inside of the docker folder and are mounted to the container’s /etc/pihole folder. When the container is started, the contents of the container’s /etc/pihole  folder will be written to my Synology NAS’s etc-pihole folder. If you are interested in backing up a container, the folders you mount for each container hold all of your personal data. These are the important folders that must be backed up. The rest is simply configuration that can be created on a separate NAS or Docker installation.

This next part is a little tricky – you can overwrite a specific file on the container by creating a local version of that file and selecting the exact path where that file exists on the container. An example of that is the resolv.conf file in the screenshot below. When the container runs, the resolv.conf file on the container will be replaced with the contents of the resolv.conf file on the Synology NAS. To reiterate, if you want to update a file on the container, create a local file on your Synology NAS and map that file to the container’s internal file. 

2. Macvlan & Bridge Network Interface

There are situations where a docker container will use certain ports (80/443 for example) and the host network interface already uses those ports for something else. When this occurs, a port conflict will stop the container from functioning properly. In situations like this, you have two main ways of fixing the problem:

1. Change the local port so that you’re using something different. For example, if the Docker container wants to use port 80, change the Local Port to be something different, like 8080 as shown below. To access the Docker container, you’d then use your Synology NAS’s IP address and the local port (http://[SYNOLOGY_NAS_IP]:8080).

2. Create a macvlan network interface and a bridge network. A macvlan network interface will avoid all port conflicts as you’re specifying a unique IP address that the container you’re creating will use. This means that you’ll access that container using a completely different IP address than your Synology NAS. By default, your host (Synology NAS) will be unable to communicate with your container. For this reason, a bridge network is required so that the host (Synology NAS) and the container can communicate. To be clear, if the Synology NAS needs to communicate with the container, you will use the bridge network IP address and NOT the macvlan IP address.

2.1 How to Create Macvlan & Bridge Network Interfaces

1. SSH into your Synology NAS using your favorite SSH tool.

2. First, we need to determine what network interfaces currently exist (on your Synology NAS) and note down the adapter name. To do this, run the command below and note down the network interface name that has your Synology NAS’s IP address (in this example, mine is eth0).

ifconfig

3. Next, you need to run the command below while substituting the correct subnet (most are 192.168.1.0/24 by default). You also need to pick an IP address that you’d like to use that’s not currently in use. I will be using 192.168.1.198. NOTE: ph_network will be the name of the network (you can substitute this as you’d like).

sudo docker network create -d macvlan -o parent=eth0 --subnet=192.168.1.0/24 --gateway=192.168.1.1 --ip-range=192.168.1.198/32 ph_network

Our network is now created. We can then exit our SSH session and disable it in DSM (if you won’t be using it). If you are disabling it and created a firewall rule for it, you should inactivate the firewall rule as well.

4. Next, we need to create a bridge network. This is what will allow our host (NAS) to communicate with our container. Open Docker and navigate to the Network section. Select Add and enter a subnet that’s not currently in use. The IP address of the bridge I am creating will be 192.168.10.2. NOTE: ph_bridge will be the name of the network – you can substitute this to be the name you’d like.

7. Our new networks are now created. We can then exit our SSH session and disable it in DSM (if you won’t be using it). If you are disabling it and created a firewall rule for it, you should inactivate the firewall rule as well.

8. When you’re creating your container, remove the bridge network and add the two networks (ph_network and ph_bridge, but yours might be named differently) to the container.

The container will now use the correct networks! You will avoid any port conflicts that would have occured, have a unique IP address for the container, and be able to communicate between the host (Synology NAS) and the container using the bridge network!

3. Environment Variables

By default, many Docker containers have environment variables that you can modify to change the settings of the container. There aren’t standard environment variables across containers and while some share variable names, it’s always suggested to view the documentation and determine which environment variables you’d like to use. The container will come standard with certain variables, but you have the option of changing them or adding new ones before the container is created.

This is an example of the Pi-Hole environment variable details listed in the documentation.

In the Docker container on your Synology NAS, the Environment section is where you can add, remove, or change environment variables.

4. How to Access a Container via Command-Line Interface (CLI)

There are certain situations where you will need or want to access the container’s files. Whether you need to modify something (by mounting a file volume) or view the structure, there’s a way to do it on a Synology NAS, but it must be done through SSH.

1. Start your container! If the container is not started, you will not be able to access the container!

2. Ensure you can SSH into your Synology NAS. Open Control Panel, select Terminal & SNMP, and Enable SSH service. If you are using Synology’s Firewall, ensure that you allow port 22 traffic. I created a video on how to SSH into your Synology NAS if you have any problems.

3. Run the command below to list the running containers. Copy the Container ID.

sudo docker container ls

4. Run the command below and substitute the container ID found above.

sudo docker exec -it CONTAINER_ID bash

5. You will now be connected as the root user for the container!

5. Docker Compose – Synology NAS

It might come as a surprise to some, but you can use Docker Compose as soon as Docker is installed on a Synology NAS. For anyone that doesn’t know, Docker Compose allows you to create containers off a YAML configuration file with a single command. Everything is executed through the command-line interface (CLI) and some users find it easier. If you’re going to use this, you might want to update Docker Compose as it’s a slightly outdated version.

A few benefits of Docker Compose on a Synology NAS:

• Everything is managed through the command-line interface (CLI). If you’re comfortable in the CLI, you will most likely find it much easier than manually configuring containers in Synology’s GUI.
• Docker Compose is system agnostic, meaning that the configuration file and data folders can be transferred to any other system running Docker Compose and it will function as expected. This is a stark difference from Synology’s Docker GUI, as you can back up the important container data, but you can’t port it over to a different operating system easily.

A few downsides of Docker Compose on a Synology NAS:

• Everything is done through the command-line interface (CLI). If you’re not comfortable in the CLI, it’s probably easier for you to manage everything in the GUI.
• Since the Docker Compose file holds all of the configuration, you need to ensure that this file is setup perfectly or you will be deleting/recreating the containers regularly to test and ensure everything works as expected.

5.1 How to Create a Container using Docker Compose

1. Move the docker-compose.yaml file that you created to the folder of the container that you’ll be creating.

2. Ensure you can SSH into your Synology NAS. Open Control Panel, select Terminal & SNMP, and Enable SSH service. If you are using Synology’s Firewall, ensure that you allow port 22 traffic. I created a video on how to SSH into your Synology NAS if you have any problems.

3. Navigate to the docker folder location on your Synology NAS and the subfolder for the container that you’ll be creating. For most people, the folder will be stored on volume1, but if you’re using multiple volumes, it could be something different.

cd /volume1/docker/[conatiner_folder]

4. After confirming that the docker-compose.yaml file is located in the current folder, run the command below to create the container. The container will now start!

sudo docker-compose up --detach

6. Conclusion – How to Use Docker on a Synology NAS

There are a ton of different Docker containers that you can create on a Synology NAS. I’m hoping that the video provided explained everything in an easily understood way, but it’s important to highlight how the Docker GUI works so that you can install any container you’d like. The process will be the same for all containers and hopefully showed you how to use Docker on a Synology NAS!

As always, if you have any questions, please leave them in the comments!