Pi-hole Ad Blocker + Cloudflare Tunnel Client via Docker Compose

* credit goes to apavamontri for original code (see: https://github.com/apavamontri/pi-hole-cloudflared-docker) *

BLUF: This project will allow you to use Docker Compose to run Pi-hole and Cloudflare Tunnel Client in tandem to achieve DNS-Over-HTTPS. Not to mention network-level ad blocking!

NOTE: If your use case is to block YouTube or Hulu ads... find another use case 😜.

DISCLAIMER: This is an educational experience aimed at deepening one's understanding of networking and containerization. Pi-hole is open-source software licensed under the European Union Public License (EUPL), which allows for its free use and modification. Please refer to this link for trademark rules and brand guidelines. As always, use your best judgement and/or the Internet for guidelines on things you should and should not be doing with this software.

DISCLAIMER II: There are still updates I'd like to make to this repo (i.e., Docker Compose .env file, etc.) and I will, in time...

Requirements

• Docker Compose or Docker Desktop (Docker install scripts for RHEL/CentOS Stream 8-9, Pi OS, and macOS included in this repo)

• Your pick of operating system, generally... (Windows installs will require WSL v1.2 or later) (macOS version 10.13 -- High Sierra -- and newer is what ChatGPT and Google Gemini reccommend) (Most flavors of Linux are supported, but Google is always your friend; I'm using CentOS Stream 9)

• Preferably at least 4GB of RAM (2GB might work, but you likely won't be happy with it)

• (OPTIONAL) Cloudflare Zero Trust account for enhanced DNS capabilities

Build Instructions

i. (OPTIONAL) Create/log into your Cloudflare account and Navigate to Zero Trust from the lefthand menu. Expand Gateway and select DNS Locations.

ii. (OPTIONAL) Click the blue Add a location button. Choose whichever name you'd like (this matters to no one but you), then click the Add IP button; this should auto-populate with your current public address.

iii. (OPTIONAL) Check the Set as Default DNS Location box and click Add location in the bottom-right.

iv. (OPTIONAL) Click on your newly created location under the Location name menu. Under Location details, record the two IPv4 addresses as well as the DNS over HTTPS URL. Save those three values for later. (Those IPv4 addresses are essentially your personal 1.1.1.1 and 1.0.0.1 with enhanced security options)

1. Make sure Docker is running by entering the following command in the terminal:

docker --version

It should return something like this:

Docker version 20.10.21, build baeda1f

2. You can change the configuration values of Pi-hole and Cloudflare Tunnel Client in the docker-compose.yml file. Port configs should generally be left as is, unless you have specific requirements based on your environment. IP address ranges can be left as is, as Docker will create the bridge network for you (check notes at the end of that file as well as the troubleshooting steps in one of the install-docker_* scripts for details on how to specify existing external networks). I advise you leave the CONTAINER names as is; another script relies on them being named, "pihole" and "cloudflared." HOSTNAME changes will affect nothing but the joy in your heart.

   • Docker Pi-hole's Environment Variables
   • Cloudflare Tunnel Client's Environment Variables

3. To build the Docker containers, run build-pihole.sh:

sudo ./build-pihole.sh

This bash script will:

• Ask for your intended Web Admin password (in 'silent mode' for added security; i.e., you won't see characters as you type).

• Start Docker Compose (in daemon mode).

• Build your containers to spec (successfully, one would hope).

4. Run the following command to check basic stats for your newly erected containers:

docker container ls

If you see either container stuck in a Restarting state, something went wrong during the build ("This looks like a job for..." you). You can try re-composing (or restarting either stuck container) as a first troubleshooting step:

./reload-pihole.sh

<OR>

docker restart <container_hostname>

Pi-hole Web Admin UI

Once the Pi-hole Docker container has started, you can access Pi-hole's Web Admin UI at http://localhost:8061/admin.

Enter the Web Admin password you set earlier.

If the password needs to be reset, run the following command, replacing <password> with you intended password:

docker exec <pihole_container-name> pihole -a -p <password>

• (Leaving <password> blank will remove the password requirement altogether.)

You can check the Upstream DNS Servers by navigating to Settings from the lefthand menu and selecting the DNS tab. You should see the IP address set for your Cloudflare Tunnel Client under Custom 1 (IPv4).

Network Configuration

This last and most important step depends on your network setup and deployment strategy.

• Follow this guide on DHCP configurations for your containers. If deploying network-wide, this will be crucial.

  • ** I recommend going with a macvlan network setup (dedicated IP for router DNS configs + no need for Pi-hole host port forwarding).
    • (See instructions in the custom-network.sh file for additional detail on setting this up)

• Follow this detailed guide on configuring your DNS.

• Follow this post-install guide for additional guidance.

• NOTE: If you have your Pi-hole container up and running, but Cloudflared is still misbehaving, you can deploy the Pi-hole container on its own: simply change the DNS servers Pi-hole is using under Settings (see: Pi-hole Web Admin UI section). Set the two custom IPv4 addresses to the Cloudflare DNS addresses you recorded earlier <OR> use one of the preset DNS locations (I'd still recommend choosing Cloudflare's 1.1.1.1, if nothing else...).

• Note: I could have mentioned firewall configurations earlier than now... I've given you more than either of us needs, so I'm gonna leave this up to your ingenuity (read: ability to perform Google searches) (sorry; perks of AuDHD... when I'm tired, I'm tired...).

  • The basic command (for Linux users) is:

   sudo firewall-cmd --add-port=<port_num>/<protocol> --permanent
  

  (where <port_num> is the port number, and <protocol> is the Transport-layer protocol: either tcp or udp; both for port 53)

  • ... followed by a:

  sudo systemctl reload firewalld

  (you're welcome... 😁).