Deploying Pi-hole

Introduction

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole to protect your devices from unwanted content. By intercepting DNS requests and blocking those that match known advertising and tracking domains, Pi-hole provides ad-free browsing for every device on your network without requiring individual browser extensions or app modifications.

Originally designed for Raspberry Pi, Pi-hole has evolved into a robust DNS server solution that runs on any Linux system or Docker container. The application includes a comprehensive web interface for monitoring queries, managing blocklists, and configuring DNS settings.

Key highlights of Pi-hole:

Network-Wide Blocking: Protect all devices on your network from ads and trackers
DNS Sinkhole: Block requests at the DNS level before connections are made
Web Interface: Intuitive dashboard for monitoring and configuration
Query Logging: Detailed logs of all DNS queries and blocked requests
Custom Blocklists: Add community-maintained or custom blocklists
Whitelist/Blacklist: Fine-tune blocking with custom domain lists
DHCP Server: Optional DHCP functionality for network management
Statistics: Visual graphs and metrics for network activity
Regex Support: Advanced pattern matching for domain blocking
Group Management: Apply different rules to different client groups
API Access: Query statistics and manage Pi-hole programmatically
100% Open Source: GPL-2.0 licensed with active community development

This guide walks through deploying Pi-hole on Klutch.sh using Docker, configuring DNS settings, and setting up the application for production use.

Why Deploy Pi-hole on Klutch.sh

Deploying Pi-hole on Klutch.sh provides several advantages for network-wide ad blocking:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Pi-hole without complex orchestration. Push to GitHub and your DNS server deploys automatically.

Persistent Storage: Attach persistent volumes for configuration, blocklists, and query logs. Your settings survive container restarts and redeployments.

Always-On Availability: Pi-hole requires high availability since it handles DNS for your network. Klutch.sh provides reliable uptime without managing infrastructure.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your network size and query volume.

Environment Variable Management: Securely store web interface passwords through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Pi-hole admin interface for easy access.

Prerequisites

Before deploying Pi-hole on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Pi-hole configuration
Basic familiarity with Docker and DNS concepts
Network configuration access to point devices to your Pi-hole
(Optional) A custom domain for your Pi-hole interface

Understanding Pi-hole Architecture

Pi-hole consists of multiple integrated components:

FTL (Faster Than Light): The core DNS server based on dnsmasq, handling DNS resolution and blocking.

Gravity Database: SQLite database containing blocklists and domain information.

Web Interface: Lighttpd-powered dashboard for administration and monitoring.

API: RESTful API for programmatic access to statistics and configuration.

DHCP Server: Optional DHCP functionality for automatic client configuration.

Query Logger: Records all DNS queries for analysis and debugging.

Preparing Your Repository

To deploy Pi-hole on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

pihole-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM pihole/pihole:latest

# Environment variables
ENV TZ=${TZ:-UTC}
ENV WEBPASSWORD=${WEBPASSWORD}
ENV PIHOLE_DNS_=${PIHOLE_DNS_:-8.8.8.8;8.8.4.4}
ENV DNSSEC=${DNSSEC:-false}
ENV REV_SERVER=${REV_SERVER:-false}

# Web interface theme
ENV WEBTHEME=${WEBTHEME:-default-dark}

# Interface settings
ENV INTERFACE=${INTERFACE:-eth0}
ENV DNSMASQ_LISTENING=${DNSMASQ_LISTENING:-local}

# Create required directories
RUN mkdir -p /etc/pihole /etc/dnsmasq.d

EXPOSE 80 53/tcp 53/udp

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD dig +short +norecurse +retry=0 @127.0.0.1 pi.hole || exit 1

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Environment Variables Reference

Variable	Required	Default	Description
`WEBPASSWORD`	Yes	-	Admin interface password
`TZ`	No	UTC	Timezone for logs
`PIHOLE_DNS_`	No	8.8.8.8;8.8.4.4	Upstream DNS servers
`DNSSEC`	No	false	Enable DNSSEC validation
`REV_SERVER`	No	false	Enable reverse DNS
`WEBTHEME`	No	default-dark	Web interface theme
`DNSMASQ_LISTENING`	No	local	DNS listening mode

Deploying Pi-hole on Klutch.sh

Once your repository is prepared, follow these steps to deploy Pi-hole:

Generate a Secure Web Password

Create a strong password for the Pi-hole admin interface. Store this securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Pi-hole deployment configuration"
git remote add origin https://github.com/yourusername/pihole-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “pihole” or “dns-blocker”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Pi-hole Dockerfile.

Configure Traffic Settings

Pi-hole requires both HTTP and DNS traffic. You may need multiple configurations:

HTTP for the web interface on port 80
TCP/UDP for DNS on port 53

Note: DNS traffic configuration may require special TCP app settings.

Set Environment Variables

Add the following environment variables:

Variable	Value
`WEBPASSWORD`	Your secure admin password
`TZ`	Your timezone (e.g., `America/New_York`)
`PIHOLE_DNS_`	`8.8.8.8;8.8.4.4` (or preferred upstream DNS)
`DNSSEC`	`true` (recommended for security)

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
`/etc/pihole`	1 GB	Pi-hole configuration and database
`/etc/dnsmasq.d`	100 MB	Dnsmasq configuration

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the Pi-hole container
Provision an HTTPS certificate for the admin interface

Access Pi-hole Admin

Once deployment completes, access the admin interface at https://your-app-name.klutch.sh/admin.

Initial Setup and Configuration

Accessing the Admin Interface

After deployment:

Navigate to https://your-app-name.klutch.sh/admin
Click “Login” in the left sidebar
Enter your WEBPASSWORD
Access the full admin dashboard

Configuring Upstream DNS

Set your preferred upstream DNS servers:

Go to Settings > DNS
Choose from presets or add custom servers
Consider enabling DNSSEC for security
Save changes

Recommended upstream options:

Google: 8.8.8.8, 8.8.4.4
Cloudflare: 1.1.1.1, 1.0.0.1
Quad9: 9.9.9.9

Managing Blocklists

Configure which domains to block:

Go to Group Management > Adlists
Add community-maintained blocklists
Update gravity database
Monitor blocked queries

Pointing Devices to Pi-hole

Configure devices to use Pi-hole for DNS:

Router-Level: Update your router’s DHCP settings to distribute Pi-hole as the DNS server.

Device-Level: Manually configure DNS on individual devices to point to your Pi-hole instance.

Mobile Devices: Use DNS-over-HTTPS (DoH) or VPN for mobile devices when away from home.

Advanced Configuration

Group Management

Apply different blocking rules to different clients:

Create client groups
Assign clients to groups
Configure adlists per group
Set whitelist/blacklist per group

Regex Filters

Create pattern-based blocking rules:

Navigate to Regex Filter
Add patterns for domain matching
Test patterns before applying
Use for advanced blocking needs

Local DNS Records

Configure custom DNS entries:

Go to Local DNS > DNS Records
Add hostname-to-IP mappings
Useful for local network devices
Provides easy-to-remember names

CNAME Records

Create DNS aliases:

Go to Local DNS > CNAME Records
Map hostnames to other hostnames
Useful for subdomain management

Monitoring and Statistics

Dashboard Overview

The Pi-hole dashboard displays:

Total queries today
Queries blocked
Percent blocked
Domains on blocklist
Query types distribution
Top permitted/blocked domains
Recent activity

Query Log

Analyze individual queries:

Go to Query Log
Filter by type, domain, or client
Whitelist or blacklist specific domains
Debug DNS issues

Long-Term Statistics

View historical data:

Navigate to Long-term data
View graphs over time
Analyze patterns
Export data if needed

Production Best Practices

Security Recommendations

Strong Password: Use a complex admin password
Access Control: Limit admin interface access
Regular Updates: Keep Pi-hole updated
DNSSEC: Enable for DNS security
Logging: Monitor for unusual activity

Performance Optimization

Conditional Forwarding: Enable for local hostname resolution
Rate Limiting: Configure to prevent abuse
Cache Settings: Optimize DNS cache size
Resource Allocation: Scale for query volume

Backup Strategy

Protect your configuration:

Teleporter Export: Use built-in backup feature
Volume Backups: Back up persistent volumes
Configuration Files: Save custom configurations
Blocklist Export: Save custom blocklists

Troubleshooting Common Issues

DNS Not Resolving

Symptoms: Devices cannot resolve domains.

Solutions:

Verify Pi-hole is running
Check upstream DNS configuration
Test with dig command
Review FTL logs

Web Interface Not Loading

Symptoms: Cannot access admin page.

Solutions:

Verify port configuration
Check Lighttpd service
Review web server logs
Confirm HTTPS certificate

False Positives

Symptoms: Legitimate sites being blocked.

Solutions:

Check query log for domain
Whitelist affected domains
Review blocklist sources
Use audit log to find issues

Additional Resources

Conclusion

Deploying Pi-hole on Klutch.sh gives you a powerful network-wide ad blocker with automatic builds, persistent storage, and reliable availability. The combination of DNS-level blocking and an intuitive web interface makes Pi-hole an effective tool for improving browsing experience across all your devices.

With comprehensive statistics, flexible blocklist management, and advanced filtering options, Pi-hole adapts to various network environments and blocking requirements. Whether you’re protecting a home network or managing DNS for a small organization, Pi-hole on Klutch.sh provides the foundation for a cleaner, faster, and more private internet experience.