⚫ Setup Pi-hole — DNS Ad Blocker
Deploy Pi-hole as a network-level advertisement and internet tracker blocking application. Acts as a DNS sinkhole and optionally a DHCP server for your entire network.
📦 Resources & Setup Scripts
Grab the automated bash script from GitHub to follow along.
Quick Install:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/networking/pihole/pihole-ubuntu.sh
chmod +x pihole-ubuntu.sh
sudo bash pihole-ubuntu.shTutorial Steps
1 Download & Run the Script
The script installs Docker, pulls the Pi-hole image, and starts the container. A random admin password is generated and displayed at the end.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/networking/pihole/pihole-ubuntu.sh
chmod +x pihole-ubuntu.sh
sudo bash pihole-ubuntu.sh2 Access the Admin Dashboard
Open your browser and navigate to the Pi-hole admin panel:
http://YOUR-SERVER-IP/admin3 Add Blocklists
Go to Group Management → Adlists to add blocklists. After adding, go to Tools → Update Gravity to download and apply the new block rules.
4 Configure Your Router DNS
Set your router's primary DNS server to your server's IP so all devices on the network benefit from ad blocking automatically. View query logs in the dashboard.
Ports Used
| Port | Protocol | Purpose |
|---|---|---|
| 53 | TCP/UDP | DNS Queries |
| 80 | TCP | Admin Web UI |
Files Location
/root/docker/pihole/docker-compose.ymlOverview
Pi-hole is a network-level advertisement and internet tracker blocking application that acts as a DNS sinkhole. When a device on your network tries to resolve an ad domain, Pi-hole returns a blank response instead, preventing the ad from loading. It runs on very low-powered hardware (originally designed for the Raspberry Pi) and blocks ads network-wide.
Why Use It
Pi-hole is the original self-hosted network-wide ad blocker — a DNS sinkhole that intercepts queries for known ad and tracker domains before they ever load. Unlike browser extensions that only work in one browser on one device, Pi-hole filters ads for every device on your network including smart TVs, game consoles, and mobile apps. Its long track record, large community, and extensive blocklist ecosystem mean you benefit from millions of curated blocked domains with minimal configuration. The admin dashboard gives clear visibility into what your network is doing at the DNS level.
When You Need It
Who Should Use It
Real Use Cases
Main Features
How to Use After Installation
Security Best Practices
Ports and Firewall Notes
Pi-hole requires port 53 (UDP and TCP) open on your local network for DNS queries from devices. Port 80 (TCP) is used for the admin web interface — restrict this to your LAN, not the internet. If you run Pi-hole as the DHCP server, UDP port 67 must be open on the interface serving DHCP. Do not forward port 53 from your router to Pi-hole's external IP — this would make Pi-hole an open DNS resolver on the internet, which will be abused. Pi-hole should only be accessible from within your local network.
Backup and Maintenance
Common Mistakes
Troubleshooting
Alternatives
AdGuard Home is Pi-hole's closest competitor — built in Go with DoH/DoT built in, lower RAM usage, and a more modern UI, though it lacks Pi-hole's mature DHCP management. Blocky is a lightweight Go-based DNS proxy with YAML config, suited for containerized environments. Technitium DNS Server is a more full-featured DNS server with ad blocking, zone management, and DNSSEC support. For cloud-managed DNS filtering without self-hosting, NextDNS and Cloudflare Gateway offer similar filtering with managed infrastructure.
When Not to Use It
If you need encrypted DNS (DoH/DoT) built in without additional configuration, AdGuard Home handles this more easily. If you're running a full containerized stack, Blocky integrates more cleanly as a Docker service with YAML configuration. For very small setups with only a couple of devices, a browser extension like uBlock Origin is simpler and more targeted. If your router already has DNS filtering built in (e.g. pfSense with pfBlockerNG), a separate Pi-hole may be redundant. For authoritative DNS with zone management, a dedicated DNS server is more appropriate.
Need Help Setting Up Pi-hole?
PrismaTechWork provides end-to-end infrastructure services — from initial deployment and security hardening to ongoing monitoring, automated backups, and dedicated support. Whether you need a single-server setup or a multi-site network, our team ensures your infrastructure is built right, secured properly, and maintained reliably.
Frequently Asked Questions
Do I need a Raspberry Pi to run Pi-hole?
No. Despite the name, Pi-hole runs on any Linux system — Ubuntu, Debian, Fedora, or any ARM/x86 hardware. You can run it on an old PC, a VPS, a Docker container, an LXC container in Proxmox, or a NAS device running Linux. The Raspberry Pi Zero W is popular because Pi-hole is extremely lightweight — it runs comfortably on less than 200MB of RAM and almost no CPU at idle. The install script works on any Debian/Ubuntu system with the same command.
Will Pi-hole break any websites?
Occasionally, yes — this is called a false positive. Some websites load resources from domains that appear on blocklists. When a site breaks, check the Pi-hole Query Log for recently blocked domains from that site and whitelist them. Over time you build up an allowlist for your specific usage. Start with well-curated low-false-positive lists from the Firebog ticked list section to minimize breakage.
Can Pi-hole block ads in mobile apps?
Yes, for apps that use separate ad domains for their ads. When your phone's DNS points to Pi-hole, any app that loads ads from a blocked domain will simply not show ads. This works for many apps. However, some apps like YouTube serve ads from the same domain as their content — Pi-hole cannot selectively block those. Overall, Pi-hole typically blocks 20-40% of app ads depending on which apps you use and which blocklists you have active.
How do I access Pi-hole from outside my home network?
The recommended way is to use a VPN like WireGuard Easy to connect to your home network, then use Pi-hole's local IP as your DNS while connected. Never expose Pi-hole's DNS port to the internet — it will be abused as an open resolver. For travel, WireGuard on your phone routing back to home with Pi-hole as DNS is the cleanest solution.
How do I update Pi-hole?
Run: pihole -up from the command line. This updates Pi-hole's core components, web interface, and FTL DNS engine. Pi-hole also shows an update notification in the admin UI when a new version is available. For the underlying OS packages, run apt update && apt upgrade separately. Consider setting up a cron job to run pihole -g weekly to keep blocklists fresh, separate from the application update.
Can Pi-hole and AdGuard Home run on the same server?
Not on port 53 simultaneously — both bind port 53 and they will conflict. You can run one on a non-standard port or use one as the primary DNS and the other for testing on a different IP. Most users choose one or the other. Running both on the same IP and port is not possible.
What is gravity and how often should I update it?
Gravity is Pi-hole's blocklist database — the compiled list of all domains to block, stored in /etc/pihole/gravity.db. Run: pihole -g to update it manually. Pi-hole 6 introduced automatic gravity updates — enable it under Settings. Weekly updates are sufficient for most users. The gravity database can contain millions of domains on typical blocklist configurations.
How do I temporarily disable Pi-hole for troubleshooting?
Use pihole disable from the command line or click Disable in the admin UI dashboard. You can disable for a set duration: pihole disable 5m pauses blocking for 5 minutes then re-enables automatically. While disabled, all DNS queries pass through to the upstream resolver unfiltered. Remember to re-enable it with pihole enable, or use the timed disable to avoid forgetting.