Pi-hole Docker Setup Guide

Welcome to the guide for setting up Pi-hole using Docker! 🚀 Follow these simple steps to get your ad-blocking Pi-hole up and running in no time.

Step 1: Create Necessary Directories

First, let’s create some directories to store Pi-hole’s configuration files. Open your terminal and run the following commands:

mkdir -p pihole
mkdir -p pihole/etc-pihole
mkdir -p pihole/etc-dnsmasq.d
cd pihole

Step 2: Create the Docker Compose File

Now, let’s create a docker-compose.yaml file inside the pihole directory. This file will define the Pi-hole service and its configuration. Use the template below:

# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest

    # For DHCP functionality, it is recommended to remove the port mappings below
    # and instead use: network_mode: "host"
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp" # Required only if using Pi-hole as your DHCP server
      - "80:80/tcp" # Change this if port 80 is already in use on the host (e.g., 8080:80/tcp)

    environment:
      TZ: "America/Chicago" # Set your timezone here
      # WEBPASSWORD: 'set a secure password here or it will be randomly generated'

      # Uncomment and set DNSMASQ_USER if you encounter permission issues
      # DNSMASQ_USER: "root"

      # Uncomment and set PIHOLE_DNS if you encounter "DNS resolution is currently unavailable"
      # PIHOLE_DNS_1: "1.1.1.1"
      # PIHOLE_DNS_2: "1.1.1.2"

    # Uncomment the following if you enable PIHOLE_DNS environment variables
    # dns:
    #  - 127.0.0.1

    # Volumes store your data between container upgrades
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"

    # Uncomment the following if you are using Pi-hole as your DHCP server
    # More info at https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
    # cap_add:
    #  - NET_ADMIN

    restart: unless-stopped

Step 3: Launch Pi-hole

With everything set up, it’s time to launch Pi-hole! Run the following command to start the Pi-hole service:

docker-compose up -d

Step 4: Update Pi-hole

Keeping your Pi-hole up-to-date is crucial for optimal performance and security. To update the Pi-hole container, simply run:

docker-compose pull

And that’s it! 🎉 You’ve successfully set up Pi-hole using Docker. Enjoy your ad-free browsing experience!

For more information, check out the official Pi-hole Docker GitHub repository and the Pi-hole documentation.