November 29, 2017

Running Pi-Hole inside Docker on Synology

When I first wrote about installing Pi-Hole inside Docker on my Synology NAS I came up with a solution that required a little modification to the standard DSM (see: Freeing up port 80 on Synology DSM). Whilst this worked I was never completely happy with this approach as I never want to modify system files as you can never be sure.

After a little work and a few updates to the Pi-Hole docker image I feel this is now possible without modification. Below is how I achieve this, enjoy.

Running Pi-Hole

As of 29th November 2017, for this to all work we are required to use the latest development version of the diginc/pi-hole image. I use the alpine version alpine_dev however I’m sure the debian image is still good.

The reason for this is that Adam added the ability to specify the port number that the pi-hole admin console listens on allowing us to avoid the already taken port 80 using the environment WEB_PORT (see: issue).

Once you have created your container from the development image there are a few steps in the docker wizard that are important.

Host networking

Firstly is that we are going to use the same network as the host. We do this so that Pi-Hole will be receiving the DNS requests direct and not relayed via Docker.

Port settings

As we are sharing the network with the host there are no port mapping requirements.


Lastly we configure 3 environment variables.

  • ServerIP is the IP address of your NAS.
  • DNSMASQ_LISTENING is set to all so that our DNS server will respond.
  • WEB_PORT is set to any port that you would like the admin console on. Values in the 8000 range are pretty good.

DNSMASQ_LISTENING is required as the image runs dnsmasq listening to the en0 interface which does not exist when using host networking on the Synology NAS. Alternatively you can use the INTERFACE environment variable to be more specific.

Configuring WebStation

Pi-Hole will redirect blocked DNS names to the IP of the Synology NAS. For this to respond we need to install WebStation. This will run on port 80 and will provide the blank areas where advert would have been seen.


As we don’t want to manually modify any of the DSM files we need to run WebStation with the Apache web server instead of nginx. Install Apache HTTP Server 2.4 using package manager.

You can use nginx if you prefer but this would require modifying the nginx.conf file and the possibility of this being overwritten or causing damage.

In the WebStation application you should be able to see that Apache 2.4 is installed.

Next in the general settings make sure that we select Apache as the back-end server.

WebStation files

WebStation will process requests on port 80 however most of these will not be valid paths that the Synology is expected (due to Pi-Hole mis-directing these requests) and therefore will respond with 404 file not found errors. It’s ok but not ideal. We can fix this (and this is the reason for Apache).

WebStation hosts files from /volume1/web so we need to create a new file named .htaccess (note the leading .) which contains the following.

ErrorDocument 404 /blocked-by-pihole.svg
ErrorDocument 500 /blocked-by-pihole.svg

This is now telling Apache that if you can’t find a file (will be most of the time due to Pi-Hole) then instead return the image blocked-by-pihole.svg.

And lastly place an image in the same place named blocked-by-pihole.svg.

You can use whatever image you want but be sure to update the .htaccess correctly.


I hope you didn’t find this too daunting, it’s a few steps that makes Pi-Hole behave correctly on the Synology NAS running in a Docker container. This correctly shows all client IP’s so I’m very happy.

As always, feel free to comment or ask for clarification.

Lastly, the image I used was downloaded from the Pi-Hole Block Page Project

© Tony Lawrence 2017 - Waffly Bollocks