Pi-hole in a docker container
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 ports: - "53:53/tcp" - "53:53/udp" - "67:67/udp" - "80:80/tcp" - "443:443/tcp" environment: TZ: 'America/Chicago' # WEBPASSWORD: 'set a secure password here or it will be random' # Volumes store your data between container upgrades volumes: - './etc-pihole/:/etc/pihole/' - './etc-dnsmasq.d/:/etc/dnsmasq.d/' # Recommended but not required (DHCP needs NET_ADMIN) # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities cap_add: - NET_ADMIN restart: unless-stopped
docker-compose up --detachto build and start pi-hole
Starting with the v4.1.1 release your Pi-hole container may encounter issues starting the DNS service unless ran with the following setting:
--dns=127.0.0.1 --dns=18.104.22.168The second server can be any DNS IP of your choosing, but the first dns must be 127.0.0.1
These are the raw docker run cli versions of the commands. We provide no official support for docker GUIs but the community forums may be able to help if you do not see a place for these settings. Remember, always consult your manual too!
This container uses 2 popular ports, port 53 and port 80, so may conflict with existing applications ports. If you have no other services or docker containers using port 53/80 (if you do, keep reading below for a reverse proxy example), the minimum arguments required to run this container are in the script docker_run.sh
If you're using a Red Hat based distribution with an SELinux Enforcing policy add
:zto line with volumes like so:
-v "$(pwd)/etc-pihole/:/etc/pihole/:z" \ -v "$(pwd)/etc-dnsmasq.d/:/etc/dnsmasq.d/:z" \
Volumes are recommended for persisting data across container re-creations for updating images. The IP lookup variables may not work for everyone, please review their values and hard code IP and IPv6 if necessary.
You can customize where to store persistent data by setting the
PIHOLE_BASEenvironment variable when invoking
PIHOLE_BASE=/opt/pihole-storage ./docker_run.sh). If
PIHOLE_BASEis not set, files are stored in your current directory when you invoke the script.
Port 443 is to provide a sinkhole for ads that use SSL. If only port 80 is used, then blocked HTTPS queries will fail to connect to port 443 and may cause long loading times. Rejecting 443 on your firewall can also serve this same purpose. Ubuntu firewall example:
sudo ufw reject https
Automatic Ad List Updates - since the 3.0+ release,
cronis baked into the container and will grab the newest versions of your lists and flush your logs. Set your TZ environment variable to make sure the midnight log rotation syncs up with your timezone's midnight.
There are multiple different ways to run DHCP from within your Docker Pi-hole container but it is slightly more advanced and one size does not fit all. DHCP and Docker's multiple network modes are covered in detail on our docs site: Docker DHCP and Network Modes
There are other environment variables if you want to customize various things inside the docker container:
| Docker Environment Var. | Description | | ----------------------- | ----------- | |
docker logs pihole \| grep randomto find your random pass. |
#[port number]) e.g
--net hostmode then you may have to customize this or DNSMASQLISTENING. | `DNSMASQLISTENING:
listens on all local subnets,all
permits listening on internet origin subnets in addition to local,single
listens only on the interface specified. |WEBPORT:
*Advanced/Optional* | **This will break the 'webpage blocked' functionality of Pi-hole** however it may help advanced setups like those running synology or
docker argument. This guide explains how to restore webpage blocked functionality using a linux router DNAT rule: [Alternative Synology installation method](https://discourse.pi-hole.net/t/alternative-synology-installation-method/5454?u=diginc) |DNSMASQUSER:
*Experimental Default: root* | Allows running FTLDNS as non-root. |
*Optional Default: c* | Set preferred temperature unit to
: Kelvin, orf
Fahrenheit units. |WEBUIBOXEDLAYOUT:
*Optional Default: boxed* | Use boxed layout (helpful when working on large screens) |
*Optional Default: Not Set* | Use this option to skip updating the Gravity Database when booting up the container. By default this environment variable is not set so the Gravity Database will be updated when the container starts up. Setting this environment variable to 1 (or anything) will cause the Gravity Database to not be updated when container starts up. |
While these may still work, they are likely to be removed in a future version. Where applicible, alternative variable names are indicated. Please review the table above for usage of the alternative variables
| Docker Environment Var. | Description | Replaced By | | ----------------------- | ----------- | ----------- | |
noif only one DNS should used |
To use these env vars in docker run format style them like:
Here is a rundown of other arguments for your docker-compose / docker run.
| Docker Arguments | Description | | ---------------- | ----------- | |
-p :Recommended | Ports to expose (53, 80, 67, 443), the bare minimum ports required for Pi-holes HTTP and DNS services |
-p :arguments (Cannot be used at same time as -p) if you don't run any other web application. DHCP runs best with --net=host, otherwise your router must support dhcp-relay settings. |
-e key=valuesettings. Here for convenience
docker exec -it pihole_container_name pihole -a -p- then enter your password into the prompt
-p 8080:80, but again the ads won't render properly. Changing the inner port 80 shouldn't be required unless you run docker host networking mode.
DEFAULT_HOSTenv in jwilder/proxy and you need to set the matching
VIRTUAL_HOSTfor the Pi-hole's container. Please read jwilder/proxy readme for more info if you have trouble.
sudo sed -r -i.orig 's/#?DNSStubListener=yes/DNSStubListener=no/g' /etc/systemd/resolved.conf
This will not change the nameserver settings, which point to the stub resolver thus preventing DNS resolution. Change the
/etc/resolv.confsymlink to point to
/run/systemd/resolve/resolv.conf, which is automatically updated to follow the system's
sudo sh -c 'rm /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'After making these changes, you should restart systemd-resolved using
systemctl restart systemd-resolved
Once pi-hole is installed, you'll want to configure your clients to use it (see here). If you used the symlink above, your docker host will either use whatever is served by DHCP, or whatever static setting you've configured. If you want to explicitly set your docker host's nameservers you can edit the netplan(s) found at
/etc/netplan, then run
sudo netplan apply. Example netplan:
yaml network: ethernets: ens160: dhcp4: true dhcp4-overrides: use-dns: false nameservers: addresses: [127.0.0.1] version: 2
Note that it is also possible to disable
systemd-resolvedentirely. However, this can cause problems with name resolution in vpns (see bug report). It also disables the functionality of netplan since systemd-resolved is used as the default renderer (see
man netplan). If you choose to disable the service, you will need to manually set the nameservers, for example by creating a new
Users of older Ubuntu releases (circa 17.04) will need to disable dnsmasq.
The primary docker tags / versions are explained in the following table. Click here to see the full list of tags, I also try to tag with the specific version of Pi-hole Core for version archival purposes, the web version that comes with the core releases should be in the GitHub Release notes.
| tag | architecture | description | Dockerfile | | --- | ------------ | ----------- | ---------- | |
latest| auto detect | x86, arm, or arm64 container, docker auto detects your architecture. | Dockerfile | |
v5.0| auto detect | Versioned tags, if you want to pin against a specific Pi-hole version, use one of these | | |
v5.0-buster| auto detect | Versioned tags, if you want to pin against a specific Pi-hole and Debian version, use one of these | | |
v5.0--buster| based on tag | Specific architectures and Debian version tags | | |
dev| auto detect | like latest tag, but for the development branch (pushed occasionally) | |
This version of the docker aims to be as close to a standard Pi-hole installation by using the recommended base OS and the exact configs and scripts (minimally modified to get them working). This enables fast updating when an update comes from Pi-hole.
The standard Pi-hole customization abilities apply to this docker, but with docker twists such as using docker volume mounts to map host stored file configurations over the container defaults. Volumes are also important to persist the configuration in case you have removed the Pi-hole container which is a typical docker upgrade pattern.
Do not attempt to upgrade (
pihole -up) or reconfigure (
pihole -r). New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! Just to prove you can.
docker pull pihole/pihole
docker rm -f pihole
docker run pihole/pihole( being your preferred run volumes and env vars)
Why is this style of upgrading good? A couple reasons: Everyone is starting from the same base image which has been tested to known it works. No worrying about upgrading from A to B, B to C, or A to C is required when rolling out updates, it reduces complexity, and simply allows a 'fresh start' every time while preserving customizations with volumes. Basically I'm encouraging phoenix server principles for your containers.
To reconfigure Pi-hole you'll either need to use an existing container environment variables or if there is no a variable for what you need, use the web UI or CLI commands.
Here are some relevant wiki pages from Pi-hole's documentation. The web interface or command line tools can be used to implement changes to pihole.
We install all pihole utilities so the the built in pihole commands will work via
docker execlike so:
docker exec pihole_container_name pihole updateGravity
docker exec pihole_container_name pihole -w spclient.wg.spotify.com
docker exec pihole_container_name pihole -wild example.com
The webserver and DNS service inside the container can be customized if necessary. Any configuration files you volume mount into
/etc/dnsmasq.d/will be loaded by dnsmasq when the container starts or restarts or if you need to modify the Pi-hole config it is located at
/etc/dnsmasq.d/01-pihole.conf. The docker start scripts runs a config test prior to starting so it will tell you about any errors in the docker log.
Similarly for the webserver you can customize configs in /etc/lighttpd
As long as your docker system service auto starts on boot and you run your container with
--restart=unless-stoppedyour container should always start on boot and restart on crashes. If you prefer to have your docker container run as a systemd service instead, add the file pihole.service to "/etc/systemd/system"; customize whatever your container name is and remove
--restart=unless-stoppedfrom your docker run. Then after you have initially created the docker container using the docker run command above, you can control it with "systemctl start pihole" or "systemctl stop pihole" (instead of
docker stop). You can also enable it to auto-start on boot with "systemctl enable pihole" (as opposed to
--restart=unless-stoppedand making sure docker service auto-starts on boot).
NOTE: After initial run you may need to manually stop the docker container with "docker stop pihole" before the systemctl can start controlling the container.
DNSMasq / FTLDNS expects to have the following capabilities available: -
CAP_NET_BIND_SERVICE: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) -
CAP_NET_RAW: use raw and packet sockets (needed for handling DHCPv6 requests, and verifying that an IP is not in use before leasing it) -
CAP_NET_ADMIN: modify routing tables and other network-related operations (in particular inserting an entry in the neighbor table to answer DHCP requests using unicast packets)
This image automatically grants those capabilities, if available, to the FTLDNS process, even when run as non-root.\ By default, docker does not include the
NET_ADMINcapability for non-privileged containers, and it is recommended to explicitly add it to the container using
--cap-add=NET_ADMIN.\ However, if DHCP and IPv6 Router Advertisements are not in use, it should be safe to skip it. For the most paranoid, it should even be possible to explicitly drop the
NET_RAWcapability to prevent FTLDNS from automatically gaining it.
Please report issues on the GitHub project when you suspect something docker related. Pi-hole or general docker questions are best answered on our user forums. Ping me (@diginc) on the forums if it's a docker container and you're not sure if it's docker related.