How to Deploy Pi-hole with Docker Compose: A Step-by-Step Guide

X (Twitter) Facebook Pinterest LinkedIn

Pi-hole is a popular network-wide ad blocker that doubles as your DNS server. It’s highly effective at blocking ads, tracking, and malware domains for all your devices, improving your network speed and security. Running Pi-hole in Docker is an excellent way to deploy it quickly and efficiently, especially when using Docker Compose to manage the configuration. This guide provides detailed instructions on setting up Pi-hole with Docker Compose.

Table of Contents

Prerequisites

Before you begin, make sure you have:

Docker installed on your server.
Docker Compose installed on your server.
Basic knowledge of Docker concepts and Docker Compose.
An available IP address on your network for Pi-hole.

Step 1: Create a Docker Compose File

First, create a directory for your Pi-hole project. This directory will contain your Docker Compose file (docker-compose.yml) and any additional configuration files or directories you might need.

mkdir pihole-docker && cd pihole-docker

Create a docker-compose.yml file:

touch docker-compose.yml

Open this file in a text editor and add the following configuration:

version: '3'

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp" # DHCP server (optional)
      - "80:80/tcp" # Web interface
      - "443:443/tcp" # Web interface (HTTPS)
    environment:
      TZ: 'Your_Timezone' # e.g., 'America/New_York'
      WEBPASSWORD: 'YourSecurePassword'
    # For persistent data
    volumes:
      - './etc-pihole/:/etc/pihole/'
      - './etc-dnsmasq.d/:/etc/dnsmasq.d/'
    # Recommended: MACVLAN for direct LAN access or bridge mode
    network_mode: bridge
    restart: unless-stopped

volumes:
  etc-pihole:
  etc-dnsmasq.d:

Configuration Details:

image: Specifies the Docker image to use. We’re using the latest Pi-hole image.
ports: Maps necessary ports from the container to the host. Adjust these as needed based on your network setup and whether you’re using Pi-hole for DHCP.
environment: Set your timezone with TZ and the admin password for the web interface with WEBPASSWORD. Replace 'YourSecurePassword' with a strong password of your choice.
volumes: Persistent storage for Pi-hole configuration and DNS settings to ensure your data remains intact across container restarts.
network_mode: bridge mode is used in this example. For some users, macvlan might be preferred for direct LAN access, but setup is more complex.

Step 2: Launch Pi-hole

Navigate to the directory containing your docker-compose.yml file and start Pi-hole by running:

docker compose up -d

This command will download the Pi-hole image and start the container in detached mode.

Step 3: Access Pi-hole

Once Pi-hole is up and running, you can access the admin web interface by navigating to http://your-server-ip/admin in a web browser. Log in with the password set in the WEBPASSWORD environment variable to configure your Pi-hole.

Step 4: Configure Your Network

For Pi-hole to effectively block ads across your network, you must configure your devices or router to use Pi-hole as their DNS server. This usually involves entering the IP address of your Pi-hole server in your router’s DNS settings.

Conclusion

Deploying Pi-hole with Docker Compose offers a clean and simple method to set up a powerful network-wide ad blocker. Following the steps outlined in this guide, you can enhance your network’s speed and security with minimal effort. Docker Compose makes managing, updating, and configuring Pi-hole straightforward, ensuring a smooth user experience.

Author
Recent Posts

Follow me

Anastasios Antoniadis

Anastasios Antoniadis is the founder and editor-in-chief of BORDERPOLAR... He is a software engineer, blogger, and avid gamer covering tech, gaming, and coding guides for over 4 years. He is a 2014 graduate of the Department of Informatics and Telecommunications of the University of Athens, an M.Sc. holder in Computer Science, and a Ph.D. student in Program Analysis.