Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC

hosts/synology/atlantis/pihole.yml

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