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.

VariableInformation
-e TZ=america/new_yorkChange your time zone with the correct time zone from the TZ Database.
-e WEBPASSWORD=YOURPASSChange YOURPASS with a password that you will use to access the application.
-e SERVERIP=YOUR.SERVER.IPChange YOURSERVERIP to the IP address of your docker host machine.
-v pihole:/etc/piholeVolume mapping the pihole volume that you created to the /etc/pihole folder within the container.
-v dnsmasq:/etc/dnsmasq.dVolume mapping the dnsmasq volume that you created to the /etc/dnsmasq.d folder within the container.
-p 80:80Mapping port 80 on the host machine to port 80 on the application container. This is for the admin container and to ensure that ads that are blocked on your network show up blank.
-p 53:53/tcpMapping tcp port 53 for DNS requests on the host machine to port 53 on the application container.
-p 53:53/udpSame as above, except adding udp port 53.
--restart=unless-stoppedEnsures that the container restarts if there should be a power cycle or and issue that causes the container to unexpectedly stop.

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:

Pi-Hole Admin Dashboard
Pi-Hole Admin Dashboard

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.

Pi-Hole Upstream DNS Servers
Pi-Hole Upstream DNS Servers

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.

Pi-Hole Blocklists
Pi-Hole Blocklists

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.

Running Pi-hole in Docker is Remarkably Easy! 1
Router DHCP Settings Page

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!

Running Pi-hole in Docker is Remarkably Easy! 2
Pi-Hole Dashboard Screenshot

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.

4 Comments

  1. 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.

    JE

  2. Hi,

    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.

    JE

2 Trackbacks / Pingbacks

  1. How to Install WireGuard in Docker - MYBOOAM
  2. Docker Pi-hole Manjaro Linux – Sprigs and Other Ideas

Comments are closed.