Deploying Pi-hole with DNS-over-HTTPS (DoH) using Docker: A Comprehensive Guide

This guide provides a detailed walkthrough of setting up Pi-hole, a popular network-wide ad blocker, within a Docker container and configuring it to use DNS-over-HTTPS (DoH) for enhanced privacy. We'll cover everything from initial setup to advanced configuration options, ensuring a smooth and secure deployment.

Using Docker offers several advantages when deploying Pi-hole:

• Isolation: Pi-hole runs in its own isolated environment, preventing conflicts with other applications on your host system.
• Portability: Easily replicate your Pi-hole setup across different platforms (Linux, Windows, macOS).
• Simplified Management: Docker simplifies updates and backups, making maintenance easier.
• Reproducibility: Easily recreate your environment from a Docker Compose file.

DoH encrypts your DNS queries, protecting your browsing history from potential eavesdroppers on your network or your ISP. This adds an extra layer of privacy to your internet activity compared to traditional DNS.

Before starting, ensure you have the following:

• Docker installed and running on your system.
• Docker Compose (optional, but highly recommended for easier management).
• A chosen DoH provider (e.g., Cloudflare, Google Public DNS, Quad9). We'll use Cloudflare in this example.

version: "3.9"
services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp"
      - "80:80/tcp"
      - "443:443/tcp"
    environment:
      - VIRTUAL_HOST=your.domain.com  # Replace with your domain or leave blank
      - WEBPASSWORD=yourpassword  # Set a strong password
      - TZ=America/New_York  # Set your timezone
      - DNS_PROVIDER=cloudflare  # Set your preferred DNS provider.  Options include: cloudflare, google, quad9, custom
      - DOH_SERVER=https://cloudflare-dns.com/dns-query  # Cloudflare DoH endpoint. Change if using a different provider.
    volumes:
      - ./etc-pihole:/etc/pihole
      - ./pihole-data:/etc/pihole/custom.conf

Remember to replace placeholders like your.domain.com and yourpassword with your actual values. The volumes mount configuration persists your Pi-hole data between container restarts and allows you to customize settings.

Create the directories specified in the volumes section of the docker-compose.yml file. You can usually leave the `etc-pihole` folder empty and create a `pihole-data` folder with any needed customizations.

Navigate to the directory containing your docker-compose.yml file and run:

docker compose up -d

Open your web browser and navigate to the IP address of your Docker host on port 80. You'll be prompted to set up your Pi-hole with the password you chose.

Finally, configure all your devices to use your Docker host's IP address as their DNS server. This step varies depending on your network configuration (router settings, individual device settings). After this, your devices should use Pi-hole for DNS queries, benefiting from the ad blocking and DoH provided.

If you encounter issues, check your Docker logs for errors: docker logs pihole

Ensure your firewall allows traffic on ports 53 (UDP/TCP), 67 (UDP), 80 and 443.

Double-check that your DoH server endpoint is correctly configured in your docker-compose.yml file.

Explore the Pi-hole documentation for more advanced configuration options, such as custom blocking lists, gravity updates, and more.