Pi-hole in Docker

I am using Pi-hole for DNS filtering. I run Pi-hole on a Raspberry Pi with Alpine Linux, which is not a supported distribution for Pi-hole. Instead, I run Pi-hole using its official Docker image.

The README in the repository contains a nice simple Docker Compose snippet. However, docker-compose is quite an overhead on a small Raspberry Pi, so instead I rely on starting the Pi-hole container the “old school way” with docker run. This script is based on the docker_run.sh in the Pi-hole Docker repository:

#!/bin/sh

PIHOLE_BASE="/media/mmcblk0p3/pihole"

docker run --detach \
    --name pihole \
    -p 53:53/tcp -p 53:53/udp \
    -p 80:80 \
    -p 443:443 \
    -v "${PIHOLE_BASE}/etc-pihole/:/etc/pihole/" \
    -v "${PIHOLE_BASE}/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
    --dns=127.0.0.1 --dns=1.1.1.1 \
    --cap-add=NET_ADMIN \
    --restart=unless-stopped \
    --hostname pi.hole \
    -e TZ="Europe/Copenhagen" \
    -e WEBPASSWORD="<password>" \
    -e VIRTUAL_HOST="pi.hole" \
    -e PROXY_LOCATION="pi.hole" \
    -e ServerIP="<host's LAN IP address>" \
    -e PIHOLE_DNS_="1.1.1.1" \
    pihole/pihole:v5.8.1

Some special/noteworthy/time-consuming-to-figure-out things are covered in the following subsections.

Mount points

To preserve settings between containers I have a dedicated folder with settings (in the variable PIHOLE_BASE) where selected folders in the container are mounted.

Somewhere in the docs it is suggested to also save a selection of logs in the folder /var/log/. If all logs are wanted it is sufficient to mount this folder with the option

-v "${PIHOLE_BASE}/var-log/:/var/log/"

If a specific file (like /var/log/pihole.log) is required this file must exist on the host before starting the container and the mount option above should be changed to

-v "${PIHOLE_BASE}/var-log/pihole.log:/var/log/pihole.log"

Note that if Pi-hole cannot create its logs it will fail to start. A faulty mount can cause problems, but deleting $PIHOLE_BASE/var-log and starting the container without mounting /var/log should reveal if this is the case.

To see the current logs, enter the pihole container with the command

docker exec --interactive --tty pihole bash

and navigate to /var/log.

ServerIP

Pi-hole would like to know the IP its host has on the LAN through the environment variable ServerIP.

WEBPASSWORD

The environment variable WEBPASSWORD grants access to the admin page on Pi-hole’s web interface. Some GitHub issues have been raised around Pi-hole not reading WEBPASSWORD, but I think it is working as intended in the version I am using (5.8.1).

DNS server

Pi-hole needs a DNS server for websites it has not cached set with the environment variable PIHOLE_DNS_.

Local DNS server

It is also possible to use Pi-hole as a DNS server on the LAN. So instead of accessing other computers on the LAN using their IP address, we can make a synonym in Pi-hole.

In the “admin” part of the web interface the “Local DNS” page provides an easy way of adding lookups. The configurations are saved in the file /etc/pihole/custom.list, which are also mounted on the host.

I found two blog posts on this topic.