homelab-optimized/hosts/synology/atlantis/pihole.yml

# =============================================================================
# PI-HOLE - NETWORK-WIDE AD BLOCKING AND DNS FILTERING
# =============================================================================
#
# SERVICE OVERVIEW:
# - Network-wide ad blocking and DNS filtering
# - Custom DNS server with blacklist/whitelist management
# - DHCP server capability (if needed)
# - Query logging and analytics dashboard
# - Local DNS resolution for homelab services
#
# DISASTER RECOVERY PRIORITY: HIGH
# - Critical for network functionality and security
# - Provides DNS resolution for homelab services
# - Blocks malicious domains and ads network-wide
# - Essential for maintaining network performance
#
# RECOVERY TIME OBJECTIVE (RTO): 15 minutes
# RECOVERY POINT OBJECTIVE (RPO): 24 hours (DNS logs and settings)
#
# DEPENDENCIES:
# - Volume1 for configuration and logs
# - Host network access for DNS (port 53)
# - Router configuration to use Pi-hole as DNS server
# - Internet connectivity for blocklist updates
#
# NETWORK IMPACT:
# - All devices use Pi-hole for DNS resolution
# - Router DNS settings: 192.168.1.100 (primary)
# - Fallback DNS: 1.1.1.1, 8.8.8.8 (if Pi-hole fails)
#
# =============================================================================

version: '3.3'

services:
  pihole:
    # CONTAINER IMAGE:
    # - pihole/pihole: Official Pi-hole image
    # - Includes DNS server, web interface, and FTL (Faster Than Light) daemon
    # - Regular updates with new blocklists and security patches
    image: pihole/pihole

    # CONTAINER IDENTIFICATION:
    # - pihole: Clear identification for logs and management
    # - Used in network configuration and monitoring
    container_name: pihole

    environment:
      # WEB INTERFACE CONFIGURATION:
      # - WEB_PORT=9000: Custom web interface port (default 80)
      # - Avoids conflicts with other web services
      # - Accessible at: http://atlantis.vish.local:9000/admin
      - WEB_PORT=9000

      # ADMIN PASSWORD:
      # - WEBPASSWORD: "REDACTED_PASSWORD" for Pi-hole admin interface
      # - SECURITY WARNING: Change this password immediately
      # - TODO: Move to secrets management or environment file
      - WEBPASSWORD="REDACTED_PASSWORD"  # pragma: allowlist secret  # TODO: CHANGE THIS PASSWORD

      # NETWORK CONFIGURATION:
      # - FTLCONF_LOCAL_IPV4: Pi-hole's IP address for DNS responses
      # - NOTE: This should match the actual NAS IP (192.168.1.100)
      # - TODO: Update to correct IP address
      - FTLCONF_LOCAL_IPV4=10.0.0.250  # TODO: Fix IP address

      # TIMEZONE CONFIGURATION:
      # - TZ: Timezone for logs and query timestamps
      # - NOTE: Typo in timezone (should be America/Los_Angeles)
      # - Used for accurate log timestamps and statistics
      - TZ=American/Los_Angeles  # TODO: Fix timezone typo

      # DNS DAEMON CONFIGURATION:
      # - DNSMASQ_USER=root: User for dnsmasq DNS server
      # - DNSMASQ_LISTENING=local: Listen only on local interfaces
      # - Security: Prevents DNS amplification attacks
      - DNSMASQ_USER=root
      - DNSMASQ_LISTENING=local

    volumes:
      # DNSMASQ CONFIGURATION:
      # - /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d
      # - Contains: Custom DNS configurations, local DNS entries
      # - Used for: Local domain resolution (*.vish.local)
      # - BACKUP IMPORTANT: Custom DNS configurations
      - /volume1/docker/pihole/dnsmasq.d:/etc/dnsmasq.d

      # PI-HOLE CONFIGURATION AND DATA:
      # - /volume1/docker/pihole/pihole:/etc/pihole
      # - Contains: Blocklists, whitelists, query logs, settings
      # - BACKUP CRITICAL: All Pi-hole configuration and history
      # - Size: ~100MB-1GB depending on log retention
      - /volume1/docker/pihole/pihole:/etc/pihole

    # NETWORK CONFIGURATION:
    # - host: Required for DNS server functionality
    # - Allows Pi-hole to bind to port 53 (DNS)
    # - Enables DHCP server functionality if needed
    # - SECURITY NOTE: Exposes all container ports to host
    network_mode: host

    # RESTART POLICY:
    # - always: Container restarts automatically on failure or reboot
    # - CRITICAL: DNS service must be always available
    # - Network functionality depends on Pi-hole availability
    restart: unless-stopped

# =============================================================================
# DISASTER RECOVERY PROCEDURES - PI-HOLE
# =============================================================================
#
# BACKUP COMMANDS:
# # Configuration backup:
# tar -czf /volume2/backups/pihole-$(date +%Y%m%d).tar.gz /volume1/docker/pihole/
#
# # Settings export (via web interface):
# # Admin > Settings > Teleporter > Backup
# # Save backup file to secure location
#
# RESTORE PROCEDURE:
# 1. Stop container: docker-compose -f pihole.yml down
# 2. Restore data: tar -xzf pihole-backup.tar.gz -C /volume1/docker/
# 3. Fix permissions: chown -R root:root /volume1/docker/pihole/
# 4. Start container: docker-compose -f pihole.yml up -d
# 5. Verify DNS: nslookup google.com 192.168.1.100
# 6. Check web interface: http://atlantis.vish.local:9000/admin
#
# NETWORK CONFIGURATION (Post-Recovery):
# 1. Router DNS settings:
#    Primary DNS: 192.168.1.100 (Pi-hole)
#    Secondary DNS: 1.1.1.1 (Cloudflare backup)
#
# 2. Local DNS entries (add to dnsmasq.d/02-local.conf):
#    address=/atlantis.vish.local/192.168.1.100
#    address=/calypso.vish.local/192.168.1.101
#    address=/concord-nuc.vish.local/192.168.1.102
#
# 3. Test local resolution:
#    nslookup atlantis.vish.local
#    nslookup plex.vish.local
#
# TROUBLESHOOTING:
# - DNS not working: Check port 53 availability, verify host networking
# - Web interface inaccessible: Check WEB_PORT setting and firewall
# - Slow DNS resolution: Check upstream DNS servers and network connectivity
# - Blocklists not updating: Verify internet connectivity and cron jobs
#
# EMERGENCY DNS FALLBACK:
# If Pi-hole fails completely:
# 1. Router > DHCP Settings > DNS Servers
# 2. Change to: 1.1.1.1, 8.8.8.8
# 3. Restart router DHCP or reboot devices
# 4. Restore Pi-hole service as soon as possible
#
# MONITORING AND HEALTH CHECKS:
# - DNS test: nslookup google.com 192.168.1.100
# - Web interface: curl -f http://localhost:9000/admin/
# - Query logs: docker exec pihole tail -f /var/log/pihole.log
# - Blocklist status: Check admin interface > Tools > Update Gravity
#
# SECURITY CONSIDERATIONS:
# - Change default admin password immediately
# - Regularly update blocklists
# - Monitor query logs for suspicious activity
# - Consider enabling DNSSEC validation
#
# =============================================================================