Running Pi-hole in Docker is Remarkably Easy!

Introduction

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.

Create Volumes

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

and

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 TZ, WEBPASSWORD, and SERVERIP environmental variables.

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.

Pi-Hole Setup

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.

DNS Servers

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.

Custom Blocklists

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.

Router Setup

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.

Success!

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.