Skip to main content

The Complete Pi-hole Guide

Pi-hole combined with Unbound gives you network-wide ad blocking backed by a fully recursive DNS resolver — no third-party DNS provider required. Every DNS query your network makes gets resolved directly from the root nameservers, cutting out Google DNS, Cloudflare, and everyone else in between.

This hub links to all the Pi-hole guides on this site, from initial Docker Compose setup through to DNS configuration and real-world troubleshooting.

Setup Guides​

Pi-hole + Unbound Docker Compose Setup​

The main guide. Walks through deploying Pi-hole and Unbound as side-by-side Docker containers with Docker Compose. Covers the full docker-compose.yml, Unbound configuration, network setup, and container communication. Start here if you're building from scratch.

Pi-hole DNS Configuration​

Once Pi-hole is running, this guide covers DNS configuration details — setting Pi-hole as your network's DNS server, configuring upstream resolvers, and tuning query performance for your local network.

Troubleshooting​

Fixing SERVFAIL with Pi-hole + Unbound on AWS​

If you're running Pi-hole + Unbound in Docker and hitting SERVFAIL errors when resolving certain domains (especially AWS Console), this guide diagnoses the root cause and walks through the fix. Based on a real issue encountered in production.

Frequently Asked Questions​

What is Unbound and why use it with Pi-hole?​

Unbound is a recursive DNS resolver. Instead of forwarding your DNS queries to a third party like Google (8.8.8.8) or Cloudflare (1.1.1.1), Unbound resolves queries by walking the DNS hierarchy from the root nameservers down. Pairing it with Pi-hole means your DNS is both ad-free and private — no external resolver sees your query history.

Why run Pi-hole and Unbound in Docker?​

Docker Compose makes the setup reproducible and portable. You get isolated containers for Pi-hole and Unbound that can communicate over a shared Docker network, with all configuration version-controlled in a single docker-compose.yml. If something breaks, tear it down and spin it back up.

How do I fix SERVFAIL errors with Pi-hole + Unbound?​

SERVFAIL usually means Unbound can't complete recursive resolution for certain domains. Common causes include DNSSEC validation failures, network-level issues blocking UDP on port 53, or Docker's internal DNS interfering with resolution. See the SERVFAIL troubleshooting guide for step-by-step diagnosis.

What Docker images should I use for Unbound?​

The most commonly referenced images are mvance/unbound and klutchell/unbound. The guides on this site use configurations that work with either. Check the main setup guide for the specific image and version used.

Enjoying the docs? Good.

The docs are the how. The newsletter is the what... as in, what the f*** — AI, power, Big Tech and the tech industry, through a Pasifika lens, from an engineer who's spent twenty-plus years working inside the machine. Fortnightly. No filter.

Leave whenever.

Get the newsletter →