How to Set Up Pi-Hole with Docker Compose on a Raspberry Pi

Ads are everywhere. Whether you’re browsing the internet or scrolling through social media, targeted ads seem to follow you relentlessly. For example, a simple search for a jacket often results in an avalanche of jacket ads across various sites. While tools like ad-blocker extensions or browsers such as Brave can help, these solutions are limited to individual devices.

Enter Pi-Hole, a powerful network-wide ad blocker that ensures a cleaner, faster, and more private internet experience. In this guide, we’ll walk through setting up Pi-Hole using Docker Compose on a Raspberry Pi. By the end of this tutorial, you’ll have a system-wide ad blocker working seamlessly across all your devices.

What is Pi-Hole?

Pi-Hole acts as a DNS sinkhole, blocking ads and trackers across your entire network. Think of it as a centralized ad blocker for all your devices—computers, smartphones, tablets, and even IoT devices. While the name implies it’s tailored for the Raspberry Pi, you can deploy Pi-Hole on any Linux-based system.

Here’s a quick look at how Pi-Hole works:

Your devices send DNS queries for websites.
Pi-Hole intercepts these queries and blocks those that match known ad or tracker domains.
The result? Ad-free browsing across your network.

Prerequisites

To follow this guide, you’ll need:

A Raspberry Pi (any model will do; we’ll be using Raspberry Pi 5 with 8GB RAM in this example).
SSH access enabled on your Raspberry Pi.
A wired Ethernet connection for your Raspberry Pi.
Basic familiarity with terminal commands.
Access to your router’s management interface.

Step 1: Installing Docker and Docker Compose

1. Update and Upgrade Your System

Ensure your Raspberry Pi is running the latest software:

sudo apt-get update && sudo apt-get upgrade

2. Install Docker

Docker simplifies containerized application deployment. Install it using the official script:

curl -fsSL <https://get.docker.com> -o get-docker.sh && sh get-docker.sh

3. Add Your User to the Docker Group

To avoid using sudo with Docker commands:

sudo usermod -aG docker ${USER}

Then, confirm the change:

groups ${USER}

Reboot your Raspberry Pi for the changes to take effect.

4. Install Docker Compose

Install Docker Compose, a tool for defining and running multi-container applications, Docker-Compose usually gets installed using pip3, below script installs python3 and pip3.

sudo apt-get install libffi-dev libssl-dev
sudo apt install python3-dev
sudo apt-get install -y python3 python3-pip

sudo apt install docker-compose

5. Enable Docker on Boot

Ensure Docker starts automatically when your Raspberry Pi boots:

sudo systemctl enable docker

Step 2: Setting Up Pi-Hole with Docker Compose

1. Create a Directory for Pi-Hole

Navigate to your home directory and create a folder:

mkdir ~/pihole && cd ~/pihole

2. Create a `docker-compose.yml` File

Create and edit the configuration file:

nano docker-compose.yml

Paste the following YAML configuration:

services:
  pihole:
    container_name: piholetest
    image: pihole/pihole:latest
    hostname: piholetest
    networks:
      pihole_network:
        ipv4_address: '10.0.0.51' #Amend with your static IP
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp"
      - "80:80/tcp"
    environment:
      TZ: 'Europe/London' #Amend timezone if needed
      WEBPASSWORD: 'your_password'#Amend password
    volumes:
      - '/home/USERNAME/pihole/etc-pihole:/etc/pihole' #Amend location
      - '/home/USERNAME/pihole/etc-dnsmasq.d:/etc/dnsmasq.d' #Amend location
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

networks:
  pihole_network:
    driver: macvlan
    driver_opts:
      parent: eth0 #Update ethernet adapter name
    ipam:
      config:
        - subnet: 10.0.0.0/8 #Amend network subnet range
          gateway: 10.0.0.1 #Amend gateway IP

Update the following placeholders in the configuration:

your_password: Replace with a secure admin password.
Network settings (ipv4_address, subnet, gateway): Match these to your network configuration.

The default gateway IP for home networks is generally 192.168.1.1. Applying this IP in your browser should open up the management console. Nord VPN has an article about it.

The subnet range or subnet mask is a number that divides your IP address into network and host portions. Has a default home networks have the 255.255.255.0 range. Nord VPN has an article about it too.

3. Deploy the Container

Run the following command to start Pi-Hole:

docker-compose up -d

This command launches the container in detached mode, running in the background. Confirm it’s running with:

docker ps

Step 3: Configuring Pi-Hole and Your Router

1. Access the Pi-Hole Admin Interface

Open a web browser and visit:

http://<Raspberry_Pi_IP>/admin

2. Set Up Upstream DNS Servers

In the Pi-Hole admin panel, configure upstream DNS servers such as Cloudflare’s 1.1.1.1 or Google’s 8.8.8.8. I personally use Cloudflare family DNS servers 1.1.1.3 and 1.0.0.3 which blocks malware and adult content.

3. Update Router DNS Settings

Access your router’s management interface and set the primary DNS server to the Raspberry Pi’s IP address. This ensures all devices on the network use Pi-Hole for DNS resolution.

Step 4: Enhancing Pi-Hole with Blocklists

For maximum ad-blocking efficiency, add more blocklists to Pi-Hole. A great source is Firebog.net.

Step 5: Testing Pi-Hole

To verify Pi-Hole is working:

Visit a site like Independent.co.uk that usually displays ads.
Check the Pi-Hole admin dashboard to see blocked queries in real-time.

Now you have a network-wide ad blocker running on your Raspberry Pi. Pi-Hole ensures a smoother, faster, and more private internet experience across all your devices.