Pi-hole on Docker: Complete Setup Guide

Pi-hole Logo

A step-by-step guide to deploying Pi-hole—a network-wide ad blocker—using Docker Compose. This setup uses the official Pi-hole image with host networking for optimal performance.

Prerequisites

• Docker and Docker Compose installed

• Terminal/SSH access to your server

• Ports 53 (DNS), 80 (HTTP), and 443 (HTTPS) available

Installation

1. Create Project Directory

mkdir ~/pihole && cd ~/pihole

2. Create docker-compose.yml

Paste this configuration :

# docker-compose.yml
version: "3"

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    network_mode: host  # Recommended for DNS performance
    ports:
      - "53:53/tcp"     # DNS (TCP)
      - "53:53/udp"     # DNS (UDP)
      - "80:80/tcp"     # Web interface
      - "443:443/tcp"   # HTTPS
    environment:
      TZ: "America/New_York"          # REQUIRED: Set your timezone
      WEBPASSWORD: "your_admin_pass"  # REQUIRED: Set web interface password
      FTLCONF_dns_listeningMode: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"    # Persistent config storage
    cap_add:
      - NET_ADMIN  # Required for DHCP/NTP features
    restart: unless-stopped

3. Customize Before Deployment

Setting	Action
TZ	Replace with your timezone
WEBPASSWORD	Set a secure password (or omit for random temp password)
Ports	Uncomment 67:67/udp for DHCP, 123:123/udp for NTP

4. Launch Pi-hole

docker compose up -d

First-Time Setup

Access the Web Interface

http://[YOUR_SERVER_IP]/admin

Configure Network Devices

1. Router Method (recommended): Set your router's DNS server to your Pi-hole IP

2. Device Method: Manually configure devices to use Pi-hole as their DNS server

Maintenance

Update Pi-hole

cd ~/pihole && docker compose pull && docker compose up -d --force-recreate

Common Commands

Command	Purpose
docker logs pihole	View container logs
docker exec pihole pihole -g	Update gravity (blocklists)
docker exec pihole pihole -v	Check Pi-hole version

Troubleshooting

Common Issues

• Web interface inaccessible: Check firewall rules and run docker logs pihole | grep password

• DNS not working: Verify port 53 isn't blocked: sudo lsof -i :53

• Permission errors: Ensure the etc-pihole directory exists and is writable

Pro Tip: For advanced configurations like custom blocklists or DHCP, refer to the official docs.

---

Final Notes:

• Data persists in the etc-pihole directory—back it up regularly

• Monitor logs during first launch: docker logs -f pihole