homelab/docker/stacks/pihole/README.md

Pi-hole Stack

A network-wide ad blocker that acts as a DNS sinkhole, protecting your entire network from ads, trackers, and malicious domains. Enhanced with DNSCrypt-proxy for encrypted upstream DNS queries.

Services Overview

• server: Pi-hole DNS server with web interface for ad blocking and network monitoring
• dnscrypt-proxy: Encrypted DNS proxy for secure upstream DNS resolution

Key Features

• Network-wide Ad Blocking: Blocks ads for all devices on your network
• DNS Sinkhole: Prevents requests to known advertising and tracking domains
• Encrypted DNS: DNSCrypt-proxy provides encrypted communication with upstream DNS servers
• Web Interface: Comprehensive dashboard for monitoring and configuration
• Query Logging: Detailed logs of all DNS queries with filtering capabilities
• Whitelist/Blacklist: Custom domain allow/block lists
• Multiple Blocklists: Support for various community-maintained blocklists
• Network Monitoring: Real-time network activity and top blocked domains
• DHCP Server: Optional DHCP functionality for network management

Architecture

DNS Flow

1. Client DNS requests → Pi-hole (port 53)
2. Pi-hole checks blocklists → Blocks or allows
3. Allowed requests → DNSCrypt-proxy (port 5353)
4. DNSCrypt-proxy → Encrypted upstream DNS servers
5. Response flows back through the chain

Security Features

• Encrypted Upstream: DNSCrypt-proxy encrypts DNS queries to upstream servers
• Privacy Protection: Prevents DNS queries from being monitored
• Malware Protection: Blocks known malicious domains

Links & Documentation

Pi-hole

• Official Website: https://pi-hole.net/
• GitHub Repository: https://github.com/pi-hole/pi-hole
• Documentation: https://docs.pi-hole.net/
• Docker Hub: https://hub.docker.com/r/pihole/pihole
• Community: https://discourse.pi-hole.net/

DNSCrypt-proxy

• GitHub Repository: https://github.com/DNSCrypt/dnscrypt-proxy
• Documentation: https://github.com/DNSCrypt/dnscrypt-proxy/wiki
• Docker Image: https://hub.docker.com/r/klutchell/dnscrypt-proxy

Blocklists

• StevenBlack's List: https://github.com/StevenBlack/hosts
• AdguardTeam Lists: https://github.com/AdguardTeam/AdguardFilters
• Firebog Lists: https://firebog.net/

Configuration

Environment Variables

Copy stack.env to stack.env.real and configure:

• TZ: Timezone for log timestamps
• PIHOLE_WEBPASSWORD: Password for Pi-hole web interface
• PIHOLE_DNS_PORT: DNS server port (default: 53)
• PIHOLE_HTTP_PORT: Web interface port (default: 80)
• SERVICE_DATA_ROOT_PATH: Base path for Pi-hole configuration data

DNSCrypt Configuration

The DNSCrypt-proxy configuration file is located at: ${SERVICE_DATA_ROOT_PATH}/dnscrypt/dnscrypt-proxy.toml

Network Access

• DNS Service: Port 53 (TCP/UDP) - Configure as DNS server for network devices
• Web Interface: Port 80 (or configured PIHOLE_HTTP_PORT)
• Admin Panel: Access via http://your-server-ip:port/admin

Setup Instructions

1. Network Configuration

Configure your router or devices to use Pi-hole as the DNS server:

• Router: Set DNS server to Pi-hole IP address
• Individual Devices: Configure network settings to use Pi-hole IP

2. Initial Setup

1. Access web interface at http://your-server-ip:port/admin
2. Login with configured password
3. Configure blocklists under "Group Management" → "Adlists"
4. Update gravity database to apply blocklists

3. Testing

• Visit http://doubleclick.net - should be blocked
• Check Pi-hole dashboard for blocked queries
• Verify DNS resolution is working for legitimate domains

Blocklist Management

Default Lists

Pi-hole comes with several default blocklists. Popular additions include:

• StevenBlack Unified: Comprehensive hosts file
• AdGuard Base Filter: AdGuard's main blocklist
• EasyList: Popular browser extension list
• Malware Domain List: Security-focused blocking

Custom Lists

Add custom blocklists via:

• Web interface: Group Management → Adlists
• Manual file editing: Add domains to local blocklist files

Advanced Features

Conditional Forwarding

Configure local domain resolution for internal networks.

DHCP Replacement

Pi-hole can replace your router's DHCP server for better integration.

API Access

REST API available for external integrations and monitoring.

Performance Considerations

• Memory Usage: Minimal resource requirements (~100MB RAM)
• Storage: Logs and configuration require modest disk space
• Network Impact: Negligible latency impact on DNS resolution
• Query Volume: Handles thousands of queries per minute efficiently

Monitoring & Maintenance

Dashboard Metrics

• Total queries processed
• Percentage of blocked queries
• Top blocked domains
• Query volume over time
• Client activity statistics

Log Management

• Query logs with filtering options
• Long-term trend analysis
• Privacy-focused logging controls

Dependencies

• Network access for initial blocklist downloads
• DNSCrypt-proxy configuration file
• Persistent storage for Pi-hole configuration and logs