↓ Skip to main content

How to Install Pi-hole on Raspberry Pi 5 Using Docker Compose & Unbound

How to Install Pi-hole on Raspberry Pi 5 Using Docker Compose and Unbound

I grabbed a Pi 5 a couple weekends back, wired it straight into my switch, and it hit me how much of my network traffic was still leaking raw DNS lookups to whatever resolver my router defaulted to — probably my ISP, possibly Google, I genuinely didn’t know. Every device on my network announcing every domain it visits to a third party by default. That’s the whole motivation here: stop leaking that, and stop depending on someone else’s resolver to do it.

The stack that actually gets you there is Pi-hole for blocking and sinkholing, Unbound for doing the actual recursive resolution yourself instead of forwarding to Cloudflare or Google, and Docker Compose to keep the whole thing contained and portable. Here’s roughly how the pieces split:

Component Role Why it matters
Raspberry Pi 5 Host hardware Quad-core Cortex-A76, plenty for this workload, runs cool
Docker Compose Orchestration Manages both containers, networking, restarts
Pi-hole DNS sinkhole + admin UI Intercepts requests, blocks ad/tracker lists
Unbound Recursive resolver Resolves from root servers directly, no upstream logging

Step 1: Clear Port 53
#

Raspberry Pi OS Bookworm ships with systemd-resolved running by default, and it binds port 53 for local stub resolution — which collides instantly with Pi-hole trying to claim that same port. SSH in and kill the stub listener first, or your container just won’t start.

sudo nano /etc/systemd/resolved.conf

Find the [Resolve] block and set:

[Resolve]
DNSStubListener=no

Then re-point resolv.conf and restart:

sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

Step 2: Configure Unbound
#

mkdir -p ~/pihole-stack/unbound && cd ~/pihole-stack
nano unbound/unbound.conf
server:
    verbosity: 1
    interface: 0.0.0.0
    port: 5335
    do-ip4: yes
    do-udp: yes
    do-tcp: yes
    do-ip6: no

    root-hints: "/opt/unbound/etc/unbound/root.hints"
    auto-trust-anchor-file: "/opt/unbound/etc/unbound/root.key"

    edns-buffer-size: 1232
    infra-cache-numdegs: 10000
    hide-identity: yes
    hide-version: yes
    qname-minimisation: yes
    prefetch: yes
    num-threads: 4

    private-address: 10.0.0.0/8
    private-address: 172.16.0.0/12
    private-address: 192.168.0.0/16

Nothing here needs fixing — the edns-buffer-size: 1232 value matches the post-2020 DNS Flag Day recommendation, qname-minimisation is correct for privacy, and the private-address blocks are the standard RFC1918 ranges so Unbound doesn’t try to recursively resolve your own LAN addresses out to the internet. Grab the root hints file so Unbound knows where the root servers actually are:

curl -o unbound/root.hints https://www.internic.net/domain/named.root

Step 3: The Compose File
#

This is where most older guides break on a current setup, in three separate ways. First, Docker Compose port mappings only accept tcp or udp as the protocol — 80:80/http and 443:443/https aren’t valid syntax and Compose will reject them outright. Second, the DNS upstream variable is often written as DNS1, which isn’t what the current Pi-hole image reads — the real variable is PIHOLE_DNS_, and it takes a semicolon-separated list if you ever want to add a fallback. Third, and the one that actually matters most: Pi-hole v6 dropped WEBPASSWORD entirely. If you’re pulling pihole/pihole:latest today, that variable just gets ignored and you’ll get a randomly generated password instead of the one you set. The current variable is FTLCONF_webserver_api_password.

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    environment:
      TZ: 'UTC'
      FTLCONF_webserver_api_password: 'change_this_to_a_secure_password'
      PIHOLE_DNS_: '172.20.0.10#5335'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
      - "443:443/tcp"
    restart: unless-stopped
    networks:
      pihole_net:
        ipv4_address: 172.20.0.5

  unbound:
    image: mvance/unbound:latest
    container_name: unbound
    volumes:
      - ./unbound:/opt/unbound/etc/unbound/
    restart: unless-stopped
    networks:
      pihole_net:
        ipv4_address: 172.20.0.10

networks:
  pihole_net:
    ipam:
      config:
        - subnet: 172.20.0.0/16

I also dropped the version: "3.8" line entirely — current Docker Compose doesn’t need it, and leaving it in just gets you an “obsolete” warning on every up. Everything else here was sound: the static IPs on the bridge network mean Pi-hole and Unbound always find each other at the same addresses regardless of start order, and pointing Pi-hole’s upstream at 172.20.0.10#5335 — Unbound’s container IP, on the port Unbound’s actually listening on — is exactly right.

Step 4: Launch and Verify
#

docker compose up -d
docker compose logs -f

Watch for both containers coming up clean — no port-binding errors, no crash loops. If Pi-hole fails to bind port 53, that almost always means step 1 didn’t fully take; double check systemd-resolved actually released the port with sudo ss -tulpn | grep :53 before you dig further.

Once it’s up, confirm Pi-hole is actually forwarding to Unbound and getting real recursive answers back, not just handing you a cached response from somewhere upstream:

dig @127.0.0.1 -p 53 example.com

A healthy response here comes back fast, with your own Pi-hole as the responding server. If it hangs or times out, check docker compose logs unbound — a missing or corrupted root hints file is the usual culprit.

Last step: log into http://<your-pi-5-ip>/admin with the password you actually set through FTLCONF_webserver_api_password, then go into your router’s DHCP settings and point the DNS server at your Pi’s IP instead of whatever your ISP handed out. Every device on the network picks that up automatically on their next lease renewal — no per-device configuration needed.

That’s the whole stack: Pi-hole doing the blocking, Unbound doing the resolving, Docker keeping both of them contained and restarting themselves if anything crashes. Nothing upstream ever sees your lookups again.

Melvin
Author
Melvin
I am a software developer building high-performance local AI tools and web architectures. I created Sablegrid, a platform that automates project scoping end to end. Stellar Tech Labs is where I write up what I learn along the way.

Related

Comments