docs: add numerous README.md

docker/stacks/pihole/README.md

@@ -0,0 +1,144 @@
+# 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