Pi-hole

intermediate

Network-wide ad blocking DNS server.

Overview

Pi-hole is a network-level advertisement and Internet tracker blocking application which acts as a DNS sinkhole. Originally developed for the Raspberry Pi, it has evolved into a powerful network-wide ad blocking solution that intercepts DNS requests and blocks queries to known advertising and tracking domains before they reach your devices. Pi-hole works by replacing your default DNS server with its own, filtering out malicious and unwanted domains while forwarding legitimate requests to upstream DNS providers. This Docker deployment creates a centralized DNS filtering solution that protects all devices on your network simultaneously. Pi-hole intercepts DNS queries from any device configured to use it, checks requests against continuously updated blocklists containing millions of known ad and tracker domains, and either blocks malicious requests or forwards legitimate ones to upstream DNS servers like Cloudflare or Google. The container includes both the DNS filtering engine and a comprehensive web interface for monitoring and management. This setup is ideal for home network administrators, privacy-conscious users, and small businesses wanting to reduce bandwidth usage while improving browsing security. Unlike browser-based ad blockers that only protect individual browsers, Pi-hole protects all network traffic including smart TVs, mobile apps, IoT devices, and any connected device making DNS queries. The solution requires minimal maintenance once configured and provides detailed analytics about blocked content and network behavior.

Key Features

Network-wide DNS-based ad and tracker blocking for all connected devices
Real-time query logging with detailed statistics and visual dashboards
Support for custom blocklists and whitelist management with regex filtering
Built-in DHCP server option for simplified network configuration
Group management system for applying different filtering policies to device categories
API integration for automation and third-party tool connectivity
Upstream DNS server configuration with support for DNS-over-HTTPS
Query type analysis showing blocked vs allowed requests with historical data

Common Use Cases

1Home network protection blocking ads on smart TVs, gaming consoles, and IoT devices
2Small office networks reducing bandwidth usage and improving productivity
3Parental controls blocking inappropriate content categories for children's devices
4Privacy-focused households preventing tracking and data collection across all devices
5Developer environments testing applications without advertising interference
6Homelab setups providing DNS services with integrated security filtering
7Remote work locations ensuring consistent ad blocking across company devices

Prerequisites

Minimum 512MB RAM available for container operations and query caching
Static IP address or reserved DHCP lease for consistent DNS server configuration
Network access to ports 53 (DNS) and 80 (web interface) without conflicts
Router administration access to configure DHCP DNS settings network-wide
Understanding of DNS concepts and network configuration basics
Firewall configuration allowing DNS traffic to and from the Pi-hole container

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  pihole: 
3    image: pihole/pihole:latest
4    container_name: pihole
5    restart: unless-stopped
6    environment: 
7      TZ: UTC
8      WEBPASSWORD: ${WEBPASSWORD}
9    volumes: 
10      - pihole_data:/etc/pihole
11      - pihole_dnsmasq:/etc/dnsmasq.d
12    ports: 
13      - "53:53/tcp"
14      - "53:53/udp"
15      - "80:80"
16    cap_add: 
17      - NET_ADMIN
18
19volumes: 
20  pihole_data: 
21  pihole_dnsmasq:

.env Template

.env

1WEBPASSWORD=changeme

Usage Notes

1Docs: https://docs.pi-hole.net/
2Admin at http://localhost/admin - login with WEBPASSWORD
3Set your router DNS to Pi-hole's IP for network-wide blocking
4Blocks ads, trackers, and malware domains via DNS
5Add custom blocklists in Group Management > Adlists
6Monitor blocked queries in real-time dashboard

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  pihole:
5    image: pihole/pihole:latest
6    container_name: pihole
7    restart: unless-stopped
8    environment:
9      TZ: UTC
10      WEBPASSWORD: ${WEBPASSWORD}
11    volumes:
12      - pihole_data:/etc/pihole
13      - pihole_dnsmasq:/etc/dnsmasq.d
14    ports:
15      - "53:53/tcp"
16      - "53:53/udp"
17      - "80:80"
18    cap_add:
19      - NET_ADMIN
20
21volumes:
22  pihole_data:
23  pihole_dnsmasq:
24EOF
25
26# 2. Create the .env file
27cat > .env << 'EOF'
28WEBPASSWORD=changeme
29EOF
30
31# 3. Start the services
32docker compose up -d
33
34# 4. View logs
35docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/pihole/run | bash

Troubleshooting

DNS resolution fails after startup: Ensure no other services are using port 53 and check firewall rules allowing DNS traffic
Web interface shows 'Unable to connect to Pi-hole API': Verify WEBPASSWORD environment variable is set and container has proper file permissions
High memory usage with query logging: Reduce log retention period in Settings > API/Web interface or increase container memory limits
Blocked domains still showing ads: Clear device DNS cache and verify devices are actually using Pi-hole as DNS server
DHCP conflicts after enabling Pi-hole DHCP: Disable DHCP on your router first, then enable Pi-hole DHCP feature
Container fails to start with permission errors: Ensure Docker has sufficient privileges and add NET_ADMIN capability for DNS operations

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

pihole

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download