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.confFind the [Resolve] block and set:
[Resolve]
DNSStubListener=noThen re-point resolv.conf and restart:
sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolvedStep 2: Configure Unbound #
mkdir -p ~/pihole-stack/unbound && cd ~/pihole-stack
nano unbound/unbound.confserver:
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/16Nothing 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.rootStep 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/16I 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 -fWatch 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.comA 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.