Free your Synology ports for Docker

(23rd July 2024) It’s been over 5 years since I wrote this post originally to remind me how I did this. It has also been brought to my attention that this is linked from the official Pi-hole docs which is awesome. Therefore I owe it to you all to bring this guide firmly into 2024, compatible with DSM 7.2 and Docker Compose.

I’ve been running Pi-Hole on my Synology for many many years. It took me a while to figure out how to run it on my Synology the way I was happy which is why I wrote the previous guide a few years ago. (see: Running Pi-Hole inside Docker on Synology)

Although this has helped me and many others, I was never quite happy about the outcome and have strived to find a better way. It didn’t feel sensible to rely on WebStation or anything external to the docker container. Thankfully I stumbled upon a docker network driver named macvlan.

Note: I will be using the command line in this guide however the containers will still be visible in the Synology Contaner Manager and can also be controlled using it if preferred. Whilst I discuss the individual commands I would advise using the docker compose method as this creates everything together.

Using macvlan for networking

Macvlan is a network driver provided by Docker, the following is an extract from the documentation

Some applications, especially legacy applications or applications which monitor network traffic, expect to be directly connected to the physical network. In this type of situation, you can use the macvlan network driver to assign a MAC address to each container’s virtual network interface, making it appear to be a physical network interface directly connected to the physical network.

So the idea is that we will create our own docker network using the macvlan driver using the same note configuration as our host, this will then allow us to connect our Pi-hole container onto this network for which we can assign it it’s own MAC. This will then appear to be directly connected on our host network but will have it’s own IP and therefore all network ports available. It’s like having both host and bridged networking together.

A new network can be easily created using the following command (but hold off, we’ll go into actually doing this later using docker compose files)

In all my examples I will be using the network 192.168.123.x. If you use any of the downloaded files please update these entries to your specific network.

$sudo docker network create 
    —driver=macvlan 
    —gateway=192.168.123.1             # your default gateway
    —subnet=192.168.123.0/24 
    -o parent=eth0                     # eth0       - this is your ethernet device
    my-network                         # my-network - you can name this anything you want

Making things easier using docker compose

I’m quite a lazy guy when if comes to repitition. I quickly became fed up of clicking around the docker UI to create containers, update containers and to modify them. Luckily docker comes with a way to automate this setup with the command docker-compose. I now use this to create all my containers that I run but in this example we will focus on Pi-Hole.

Docker compose requires a configuration file that is in YAML format. This is just plain text so can be edited using any application however, whitespace is important so no TAB characters please.

In the docker compose file we can create the network (macvlan), we can create our service (Pi-Hole) and optionally assign specific MAC and IP addresses. I will explain each section individually to build up the complete picture. I will also attach a download link at the bottom of the article so that you are not forced to copy & paste.

If you want to follow along then ssh to your Synology, create a file name docker-compose.yaml and add the following snippets. You can then try this out running the following command in the same place as the file you created. This command will re-create the config each time so you do not need to delete previous versions.

$sudo docker-compose up

For more information try sudo docker-compose up —help

Start by specifying the version (now optional).

version: “3.8”                            # 3.8 is the latest but can now be omitted

Defining the network:

networks:
  pihole_network:                         # Reference to the network used in docker compose files
    name: pihole_network                  # A user visible name of the network
    driver: macvlan                       # Use the macvlan network driver
    driver_opts:
      parent: eth0                        # If open vSwitch is enabled use ovs_eth0 (or ovs_eth1 etc.)
    ipam:
      config:
        - gateway: 192.168.123.1          # Gateway address
          subnet: 192.168.123.0/24        # Specify subnet

This creates a new network named pihole_network using the parent network interface eth0. This will be visible in the Synology Container Manager UI under networks.

Please check your network interface using ifconfig or ip addr show and change the parent device above to match.

Next we need to add our Pi-Hole container. This can be added with the following configuration.

services:
  pihole:
    container_name: pihole          # We name our container here
    image: pihole/pihole:latest     # Latest version is 2024.07.0 as of writing this document
    hostname: pihole                # Containers hostname (optional)
    domainname: example.com         # Contaners domain (optional)
    mac_address: d0:ca:ab:cd:ef:01  # Random MAC address (optional)
    cap_add:
      - NET_ADMIN                   # Required if you are using Pi-hole as your DHCP server
    networks:
      - pihole_network              # Same name of network defined above
    dns:
      - 127.0.0.1
      - 1.1.1.1                    # Upstream DNS server
    ports:                          # Ports are not required if we are using the macvlan network driver
      - 443/tcp
      - 53/tcp
      - 53/udp
      - 67/udp
      - 80/tcp
    environment:                    # Optional environment configuration
      ServerIP: 192.168.123.199   # Change this to matche your Synology IP
      WEBPASSWORD: “”               # Leave empty for no password to the web admin pages
      VIRTUAL_HOST: pihole.example.com
    restart: unless-stopped         # Set container to always restart

We specify our containers name, image and various networking information plus the environments required by Pi-Hole.

The combination of these two configurations are all that is required to create and run Pi-Hole on your Synology NAS. The complete file can be downloaded here.¹

If you need more information the documentation can be found here.

How do we use docker compose

Assuming you have your docker compose file correctly setup (either writing your own or downloading one of mine) you can now start up Pi-Hole from the command line. If all works out then Pi-Hole should now be up and running and visible inside the Synology Docker UI.

$sudo docker-compose up -d

Docker compose requires root access which will ask for your admin password. The -d is needed to run in daemon mode, if we do not supply this then the command will block in the shell.

How do we go about updating - you might ask?

Updating to the latest image is very easy. You can run the following commands.

$sudo docker-compose pull
$sudo docker-compose up -d

Optionally you can specify the service $sudo docker-compose up pihole if you have mulitple services

This will download the new version and then re-create the updated Pi-Hole container.