homelab-pihole-dns

This skill is a hands-on reference for standing up and operating Pi-hole, a network-wide DNS ad and malware blocker, on a Raspberry Pi or any Linux host. It solves the problem of ads, trackers, and malicious domains reaching every device on a home network by routing all DNS queries through Pi-hole, which returns null responses for blocked domains and forwards the rest to an upstream resolver. It also addresses the common failure mode where devices lose internet access after Pi-hole is introduced, offering troubleshooting guidance.

The skill covers two installation paths — a pinned Docker Compose deployment and a bare-metal install on Raspberry Pi OS, Debian, or Ubuntu — plus how to point a network at Pi-hole via router DHCP, per-device DNS, or Pi-hole acting as the DHCP server. It documents blocklist (adlist) management and gravity updates, whitelisting false positives, reading the live query log, configuring DNS-over-HTTPS upstreams with cloudflared, and creating local DNS records for homelab services. Throughout, it emphasizes security-conscious practices: pinning release tags instead of using latest, storing the web password in a chmod-600 .env file kept out of git, and inspecting the installer script before running it.

It is aimed at homelab enthusiasts, self-hosters, and privacy-minded users who administer their own home network and want automatic, network-wide blocking without browser extensions. Typical use cases include first-time Pi-hole setup, migrating DNS to Pi-hole, adding blocklists, encrypting DNS queries from the ISP, and diagnosing broken DNS resolution.