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:



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= --dns= \
    --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_="" \

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.


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


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.

>> Home