Internet advertisements and trackers are everywhere. The websites you visit and your smart devices are constantly sending data to back to their manufacturers and to third party advertisers. Pi-hole is a network-level ad blocker that sits on your network and uses blacklists to determine which DNS requests to block. Installation of Pi-Hole in Docker is easy. Once set up, you can configure your router to forward DNS requests to your pi-hole server and you’ll immediately notice a difference in the websites that you visit.
This tutorial assumes you have Docker already installed on your system. If you need to install Docker, you can view the quick and easy steps to install docker post.
In order to maintain data persistence across container updates, Pi-Hole recommends that you create two volumes. One volume to store your application configuration data (
/etc/pihole) and one volume to store DNS configuration (
/etc/dnsmasq.d). To create the volumes run the following commands:
docker volume create pihole
docker volume create dnsmasq
These commands will create persistent volumes on the host system. If you would like to create volumes using a network file share (NFS), you can follow the directions outlined in this post (Note that using a NFS volume will reduce the speed of your Pi-Hole).
Docker Run Command
Now that we have our volumes created, it is time to run the Pi-Hole. To quickly get Pi-Hole up and running you can run the following command:
docker run \ --name=pihole \ -e TZ=America/New_York \ -e WEBPASSWORD=YOURPASS \ -e SERVERIP=YOUR.SERVER.IP \ -v pihole:/etc/pihole \ -v dnsmasq:/etc/dnsmasq.d \ -p 80:80 \ -p 53:53/tcp \ -p 53:53/udp \ --restart=unless-stopped \ pihole/pihole
This command uses the official Pi-Hole container image from the Docker Hub. Make sure you edit the
SERVERIP environmental variables.
Make sure to edit the variables in the command to match your setup. Below is a table of information about the variables used in the above command.
|Change your time zone with the correct time zone from the TZ Database.|
|Volume mapping the |
|Volume mapping the |
|Mapping port |
|Mapping tcp port |
|Same as above, except adding udp port |
|Ensures that the container restarts if there should be a power cycle or and issue that causes the container to unexpectedly stop.|
Once you have the Pi-Hole container up and running, you can access the web interface by opening your browser and pointing it to
http://YOURSERVERIP/admin. You’ll be presented with the following screen:
On the left, you will see the
login button. Press it and you will be presented with the admin login screen. Use the password that you defined in the
WEBPASSWORD variable in the docker run command.
Once you login, you can click
settings on the left sidebar. Then at the top, you can click
DNS to adjust the DNS servers that you want to forward requests to. The default is set to Google’s DNS servers, but I prefer to use Cloudflare. You can select as many or as few DNS servers that you would like to use. If you are running unbound in docker, you can point the DNS servers to your unbound docker instance as well.
After you select your upstream DNS servers, select save at the bottom right hand corner of the screen.
Blocklists are the lists that Pi-Hole uses to determine which requests on the network get blocked. They are sourced from the community and are updated often. Pi-Hole currently has 6 installed by default.
To add an additional blocklist to Pi-Hole all you have to do is paste the URL of the blocklist into the field below the blocklist screen then click the
Save and Update button.
One custom blocklist that I recommend to add to your installation is “The Internet’s #1 Domain Blocklist“. The URL to paste into the Pi-Hole Blocklists screen is:
https://dbl.oisd.nl. You can find other types of lists to use with your installation here.
Now that Pi-Hole in Docker is up and running it is time to point all of your network devices to the Pi-Hole container. The easiest way to do that is through your home router. You must configure your home router to have DHCP clients use Pi-Hole as their DNS server.
When you log in to your routers configuration page find the LAN (not WAN) DHCP/DNS settings section. Once you find it, you are going to want to set the DNS server to the IP address of your Pi-Hole. This is also the same address you set in the
SERVERIP variable in the docker run command. Your Pi-Hole IP address should be the only DNS server in your router DHCP settings.
Once you save these settings, restart your devices and once they come back online, they should be using Pi-Hole as their DNS server.
Now that you have Pi-Hole up and running, you can log back into the admin screen and you will start to see the requests that are being sent to Pi-Hole from your network.
It should be noted that Pi-Hole will not block 100% of the ads and cannot block ads from YouTube. But, if you browse the internet a lot or have a lot of smart home devices, it won’t take long for you see the benefit of having a Pi-Hole running on your network.
I’m using linux mint 19.3.
Your recipe fails because port 53 is held by ‘stubby,’ a dohicky
that encrypts outgoing requests, they say.
Just thought you should know.
I’m new to docker and your instructions have been very helpful.
hi can you resolve this problem on linux mint 19.3 ?
I ran across another problem with the pihole docker image. The TLS certificate is expired and I get this error:
“Error: error while loading TLS certificate in /var/lib/docker/swarm/certificates/swarm-node.crt: certificate (1 – mk63gjvvmyzhv13gafhu71h77) not valid after Fri, 06 Mar 2020 04:18:00 UTC, and it is currently Sun, 19 Jul 2020 07:38:44 PDT: x509: certificate has expired or is not yet valid”
It sounds like the image needs a newer cert.
Great post, thanks for the tutorial!
However, I got this error when using the docker run command you provided:
“DNS resolution is currently unavailable”
I followed this url:
The solution is to add the following parameter in the docker run command:
–dns 127.0.0.1 –dns 184.108.40.206