# Setting Up Pi-hole with Docker #Docker #Networking #Security ## 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. Create 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 # Optional environment variables 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 ### 1. 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 ``` ### 2. Web Interface Access - Access the web interface at `http://your-server-ip/admin` - Log in with the password set in the environment variables - Default credentials (if WEBPASSWORD not set): - Username: admin - Password: (check docker logs) ### 3. DNS Configuration #### Router Setup 1. Access your router's admin interface 2. Find DNS settings (usually under DHCP/Network settings) 3. Set primary DNS to your Pi-hole server IP 4. Optional: Set secondary DNS to a backup DNS server #### Individual Device Setup - **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 ### 1. Updating Pi-hole ```bash # Pull latest image docker pull pihole/pihole:latest # Restart container docker-compose down docker-compose up -d ``` ### 2. 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/ ``` ### 3. 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 ### 1. Common Issues - **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 ``` ### 2. 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 ### 1. Security - Change default password immediately - Use HTTPS for web interface - Implement firewall rules - Regular backups - Monitor logs for suspicious activity ### 2. Performance - Place Pi-hole close to network core - Use SSD for storage - Monitor resource usage - Regular maintenance - Keep blocklists updated ### 3. Additional Features - Consider enabling DHCP server - Set up DNS-over-HTTPS - Configure conditional forwarding - Implement custom block lists - Set up gravity sync for HA ## 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/) - [Pi-hole Subreddit](https://www.reddit.com/r/pihole/)