My previous guide for Pi-hole involved the use of Task Scheduler. Today I’m offering a recommended and excellent alternative for installing the latest Pi-hole version via Portainer. Pi-hole is a Linux network-level advertisement and Internet tracker blocking application which acts as a DNS sinkhole and optionally a DHCP server, intended for use on a private network. In this step by step guide I will show you how to install Pi-hole on your Synology NAS using Docker & Portainer.

💡Note: This guide works perfectly with the latest version of Pi-Hole v6.0.3 and DSM 7.2.2

💡Note: Check out my new guide on how to Install Pi-Hole V6 on Your UGREEN NAS.

STEP 1

Please Support My work by Making a Donation.

STEP 2

Install Portainer using my step by step guide. If you already have Portainer installed on your Synology NAS, skip this STEP. Attention: Make sure you have installed the latest Portainer version.

STEP 3

Add Google DNS. Go to Control Panel / Network / General. Check “Manually configure DNS server” and add on Preferred DNS Server: 8.8.8.8 and on Alternative DNS Server: 8.8.4.4 Click Apply. Follow the instructions in the image below.

STEP 4

Go to File Station and open the docker folder. Inside the docker folder, create one new folder and name it pihole. Follow the instructions in the image below.
Note: Be careful to enter only lowercase, not uppercase letters.

STEP 5

Now create two new folders inside the pihole folder that you previously created at STEP 4 and name them dnsmasq.d and pihole. Follow the instructions in the image below.
Note: Be careful to enter only lowercase, not uppercase letters.

STEP 6

Log into Portainer using your username and password. On the left sidebar in Portainer, click on Stacks then + Add stack. Follow the instructions in the image below.

STEP 7

In the Name field type in pihole. Follow the instructions in the image below.

Note: Copy Paste the code below in the Portainer Stacks Web editor.

services:
  pihole:
    image: pihole/pihole
    container_name: Pi-Hole
    network_mode: host
    security_opt:
      - no-new-privileges:false
    restart: on-failure:5
    volumes:
      - /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d:rw
      - /volume1/docker/pihole/pihole:/etc/pihole:rw
    environment:
      FTLCONF_webserver_api_password: Mariushosting@4
      FTLCONF_webserver_port: 8080
      TZ: Europe/Bucharest
      DNSMASQ_USER: pihole #or root NOT recommended to use root.
      PIHOLE_UID: 1026
      PIHOLE_GID: 100
    cap_add:
      - SYS_TIME
      - SYS_NICE

Note: Before you paste the code above in the Web editor area below, change the value for FTLCONF_webserver_api_password and add your own password. Mariushosting@4 is an example for a password, you should use your own password.
Note: Before you paste the code above in the Web editor area below, change the value for TZ. (Select your current Time Zone from this list.)
Note: Before you paste the code above in the Web editor area below, change the value numbers for PIHOLE_UID and PIHOLE_GID with your own UID and GID values. (Follow my step by step guide on how to do this.)

STEP 8

Scroll down on the page until you see a button named Deploy the stack. Click on it. Follow the instructions in the image below. The installation process can take up to a few minutes. It will depend on your Internet speed connection.

STEP 9

If everything goes right, you will see the following message at the top right of your screen: “Success Stack successfully deployed“.

STEP 10

🟢Please Support My work by Making a Donation. Almost 99,9% of the people that install something using my guides forget to support my work, or just ignore STEP 1. I’ve been very honest about this aspect of my work since the beginning: I don’t run any ADS, I don’t require subscriptions, paid or otherwise, I don’t collect IPs, emails, and I don’t have any referral links from Amazon or other merchants. I also don’t have any POP-UPs or COOKIES. I have repeatedly been told over the years how much I have contributed to the community. It’s something I love doing and have been honest about my passion since the beginning. But I also Need The Community to Support me Back to be able to continue doing this work.

STEP 11

The installation process can take up to a few seconds/minutes. It will depend on your Internet speed connection. Now open your browser and type in http://Synology-ip-address:8080/admin/login Type in the Password (FTLCONF_webserver_api_password) that you have previously created at STEP 7. Click Log in. Follow the instructions in the image below.

STEP 12

Your Pi-hole dashboard at a glance!

Fix: If you are experiencing the following issues:
Cannot bind to IPv4 address 0.0.0.0:123 (Address in use), IPv4 NTP server not available
Cannot bind to IPv6 address :::123 (Address in use), IPv6 NTP server not available
Go to Pi-Hole / Settings / All Settings / Switch to All settings / Click on the Network Time Sync tab/ Uncheck the ntp.ipv4.active and ntp.ipv6.active options, then click Save & Apply. Follow the instructions in the image below.

STEP 13

[Only for advanced users] Download (click on the blue link below) to download the Pi-Hole Macvlan Docker Compose. Advantages For Pi-Hole with Macvlan: Works well with NAS devices or hard port conflicts. A Macvlan network is the most advanced option since it requires more network knowledge and setup. This mode is similar to host network mode but instead of borrowing the IP of your docker host computer it grabs a new IP address off your LAN network. 🔒Note: Support my work to unlock the password. You can use this password to download any file on mariushosting forever!

👉🏻piholemacvlan.txt

🆘TROUBLESHOOTING

If you encounter issues by using this container, make sure to check out the Common Docker issues article.

Note: Many content providers (like YouTube / Reddit / Twitch / Spotify / Pandora / Facebook / Hulu) now stream/serve ads from the same servers as the content (meaning if you attempt to block the ads using a Pi-Hole you will also block the content). If you want to view YouTube without Adverts content, just use Piped or Invidious.
Note: Use Pi-Hole As DNS on Windows 11.
Note: How to Activate Dark Mode in Pi-Hole.
Note: How to Free Disk Space on Your NAS If You Run Docker.
Note: Some people may have problems launching Pi-Hole via Docker. This may be because of different settings in your Synology NAS and router. Every user has their own router settings etc. It’s really hard to troubleshoot the problem. You can also contact me via email and I will try to find a personalized solution for you.
Note: After installing Pi-hole (through Docker), Synology NAS drives are not hibernating at all. The best solution is to Disable Hibernation. This will be easier and much more beneficial overall for everything Pi-hole needs to read database of filters.
Note: Find out how to update Pi-Hole container with the latest image.

Fix: 403 Oops! Access denied. If you want to use Pi-Hole with Synology Reverse Proxy, add your DDNS like you did until now, with WebSocket, then access Pi-Hole in your browser using pihole.yourname.synology.me/admin/login At the end of your own domain name or DDNS just add /admin/login If you forget to add /admin/login at the end of your DDNS, you will receive the 403 error message.

Fix: If someone has a problem once installation is completed, and gets an error like “This site can’t be reached“, open the Pi-hole GUI and go to Settings / DNS tab and in “Interface listening behavior” change to Listen on all interfaces instead of Listen only on interface eth0. (Reported by jtd).
Fix: If your Pi-hole container keeps disconnecting, uninstall the Synology Package named “DNS Server” or “DHCP Server” which conflicts with Pi-hole on port 53 and doesn’t let your Pi-hole start.
Fix: If you get an error in Pi-hole that says Lost connection to API, restart your Pi-Hole container in Portainer. (Reported by Arjan).
Fix: If your Pi-hole container gets a DNS service not running, uninstall the Synology Package named “DNS Server” or “DHCP Server” which conflicts with Pi-hole on port 53 and doesn’t let your DNS work.
Fix: If you experience connections problems, remember to set your Synology Firewall in Control Panel / Security / Firewall / Edit Rules / Create Firewall Rules and allow Custom Port 53 Protocol All.
Fix: If you can’t play videos from CNN, in the PiHole whitelist add the following address: c.amazon-adsystem.com
Fix: How can I make Pi-Hole work over VPN connection? Go to Pi-Hole / Settings / DNS / Switch from Basic to Expert / Interface Settings window / choose Permit all origins then click Save & Apply. Follow the instructions in the image below.

Fix: If you want to run the DHCP server on docker with pi-hole, just add the cap_add: NET_ADMIN directive as per the instructions below.

services:
  pihole:
    image: pihole/pihole
    container_name: Pi-Hole
    network_mode: host
    security_opt:
      - no-new-privileges:false
    restart: on-failure:5
    volumes:
      - /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d:rw
      - /volume1/docker/pihole/pihole:/etc/pihole:rw
    environment:
      FTLCONF_webserver_api_password: Mariushosting@4
      FTLCONF_webserver_port: 8080
      TZ: Europe/Bucharest
      DNSMASQ_USER: pihole #or root NOT recommended to use root.
      PIHOLE_UID: 1026
      PIHOLE_GID: 100
    cap_add:
      - SYS_TIME
      - SYS_NICE
      - NET_ADMIN

Fix: If you experience NTP timeouts in the Pihole logs or No valid NTP replies received, check server and network connectivity errors, in your Synology Firewall, in the Deny Rule, uncheck the NTP Service, then save the settings. Follow the instructions in the image below.

This post was updated on Friday / February 21st, 2025 at 9:35 AM

Synology: Install Pi-hole With Portainer

💡Note: This guide works perfectly with the latest version of Pi-Hole v6.0.3 and DSM 7.2.2

💡Note: Check out my new guide on how to Install Pi-Hole V6 on Your UGREEN NAS.

STEP 1

STEP 2

STEP 3

STEP 4

STEP 5

STEP 6

STEP 7

STEP 8

STEP 9

STEP 10

STEP 11

STEP 12

STEP 13

👉🏻piholemacvlan.txt

🆘TROUBLESHOOTING

🧡 I Need Your Help!