Pi-hole Docker Setup

Network-wide ad blocking with Pi-hole running in Docker.

DockerNetworkingSecurityDNS

Overview

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole. When deployed via Docker, it provides a flexible and portable solution for blocking ads, trackers, and malicious domains across your entire network.

Prerequisites

  • Docker installed on your system
  • Basic understanding of networking concepts
  • Access to router settings (for DNS configuration)
  • Port 53 not in use by other services

Installation

1. Create Directory Structure

bash
# Create directories for persistent storage
mkdir -p ~/pihole/etc-pihole
mkdir -p ~/pihole/etc-dnsmasq.d
cd ~/pihole

2. Docker Compose File

yaml
# docker-compose.yml
version: "3"

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp"  # Only required if using Pi-hole as your DHCP server
      - "80:80/tcp"  # Web interface
      - "443:443/tcp"  # Web interface with SSL
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'your-secure-password'  # Change this!
      ServerIP: 'your-server-ip'  # Your server's IP address
      DNSSEC: 'true'
      DNS1: '1.1.1.1'  # Cloudflare
      DNS2: '1.0.0.1'  # Cloudflare secondary
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    dns:
      - 127.0.0.1
      - 1.1.1.1
    cap_add:
      - NET_ADMIN  # Required for DHCP
    restart: unless-stopped

3. Alternative: Docker Run Command

bash
docker run -d \
  --name pihole \
  -p 53:53/tcp \
  -p 53:53/udp \
  -p 67:67/udp \
  -p 80:80 \
  -p 443:443 \
  -e TZ="America/New_York" \
  -e WEBPASSWORD="your-secure-password" \
  -e ServerIP="your-server-ip" \
  -e DNSSEC="true" \
  -e DNS1="1.1.1.1" \
  -e DNS2="1.0.0.1" \
  -v "$(pwd)/etc-pihole/:/etc/pihole/" \
  -v "$(pwd)/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
  --dns=127.0.0.1 \
  --dns=1.1.1.1 \
  --cap-add=NET_ADMIN \
  --restart=unless-stopped \
  pihole/pihole:latest

Configuration

Initial Setup

bash
# Start the container
docker-compose up -d

# View the logs
docker logs pihole

# Get the Web interface password
docker exec -it pihole pihole -a -p

Web Interface Access

  • Access the web interface at http://your-server-ip/admin
  • Log in with the password set in the environment variables
  • Default username is 'admin'

DNS Configuration - Router Setup

  • Access your router's admin interface
  • Find DNS settings (usually under DHCP/Network settings)
  • Set primary DNS to your Pi-hole server IP
  • Optional: Set secondary DNS to a backup DNS server

DNS Configuration - Individual Devices

Windows:

powershell
# View network adapters
Get-NetAdapter

# Set DNS server
Set-DnsClientServerAddress -InterfaceIndex 12 -ServerAddresses "your-pihole-ip"

Linux:

bash
# Edit resolv.conf
sudo nano /etc/resolv.conf
# Add: nameserver your-pihole-ip

macOS:

bash
# List network services
networksetup -listallnetworkservices

# Set DNS
sudo networksetup -setdnsservers "Wi-Fi" your-pihole-ip

Maintenance

Updating Pi-hole

bash
# Pull latest image
docker pull pihole/pihole:latest

# Restart container
docker-compose down
docker-compose up -d

Backup

bash
# Backup configuration
tar -czf pihole-backup-$(date +%F).tar.gz etc-pihole etc-dnsmasq.d

# Optional: Copy to remote location
scp pihole-backup-*.tar.gz user@remote:/backup/

Monitoring

bash
# View container status
docker ps -f name=pihole

# Check logs
docker logs -f pihole

# View statistics
docker exec -it pihole pihole -c

Troubleshooting

Port 53 Conflict

bash
# Check if port 53 is in use
sudo lsof -i :53

# Disable systemd-resolved if necessary
sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved

DNS Not Working

bash
# Test DNS resolution
nslookup google.com your-pihole-ip

# Check Pi-hole logs
docker logs pihole

Performance Tuning

bash
# Increase DNS cache size
echo "cache-size=10000" | sudo tee /etc/dnsmasq.d/99-cache.conf

# Restart container
docker-compose restart

Best Practices

Security

  • Change default password immediately
  • Use HTTPS for web interface
  • Implement firewall rules
  • Regular backups
  • Monitor logs for suspicious activity

Performance

  • Place Pi-hole close to network core
  • Use SSD for storage
  • Monitor resource usage
  • Keep blocklists updated

Additional Resources

  • Pi-hole Documentation: https://docs.pi-hole.net/
  • Pi-hole Docker GitHub: https://github.com/pi-hole/docker-pi-hole
  • Pi-hole Discourse: https://discourse.pi-hole.net/
Back