nyirsh/pihole-unbound repository overview

⁠Pi-Hole + Unbound on Docker

⁠Use Docker to run Pi-Hole⁠ with an upstream Unbound⁠ resolver.

This Docker deployment runs both Pi-Hole and Unbound in a single container.

The base image for the container is the official Pi-Hole container⁠, with an extra build step added to install the Unbound resolver directly into it based on instructions provided directly by the Pi-Hole team⁠.

The Github repository⁠ is set to automatically check for a new PiHole version every day by monitoring the official Pi-Hole docker repository⁠. If a new release is detected, a new image is automatically generated and pushed to dockerhub repository⁠ and GitHub Container Registry⁠.

This configuration contacts the DNS root servers directly, please read the Pi-Hole docs on Pi-hole as All-Around DNS Solution⁠ to understand what this means.

⁠Quick Start

⁠Compose file

Download the pre-made docker-compose.yml⁠ that you can also find in this repository...

curl -SO https://raw.githubusercontent.com/nyirsh/pihole-unbound/main/docker-compose.yml

Please keep in mind that this is a very quick and dirty way to kickstart your instance, it is highly recommended that you customize the docker-compose.yml to properly match your environment requirements. If this sentence doesn't make much sense to you, I would highly recommend learning more about docker.

⁠Evironment variables

Create a .env file in the same folder where docker-compose.yml is and substitute the values to match what's required for your deployment:

HOSTNAME=pihole
DOMAINNAME=pihole.local
LOCAL_IPV4=192.168.1.10
PIHOLE_WEBPORT_HTTP=80
PIHOLE_WEBPORT_HTTPS=443

TZ=America/Los_Angeles
WEBPASSWORD=YourAdminPassword
WEBTHEME=default-dark

REV_SERVER=true
REV_SERVER_DOMAIN=local
REV_SERVER_TARGET=192.168.1.1
REV_SERVER_CIDR=192.168.0.0/16

⁠Custom variables

⁠Pi-Hole variables

For a complete list of possible variables, please refer to the Pi-Hole official documentation⁠:

⁠Run the stack!

docker-compose up -d

⁠FAQ

- Q: I also want to use Cloudflare or change some other parameters of Pi-Hole!

Please keep in mind that the docker-compose.yml and .env files provided in this repository are just an example! Feel free to customize the files so that they can match your expected experience, if you're unsure on how to do so I would highly recommend getting some knowledge on Docker⁠ first.

- Q: I am running Pi-Hole alongside other containers on the same machine but, despite setting the DNS to match the host machine IP, I still can't resolve any address!

Yep, it's a docker limitation of some sort, you can find more details here⁠. To keep it short, change these two ports in your docker-compose.yml file:

- "${LOCAL_IPV4}:53:53/tcp"
- "${LOCAL_IPV4}:53:53/udp"

- Q: Thank you for this! Do you accept donations?

A: No I do not, I really did nothing special and everything here is fully automated so I don't think I deserve any kind of donation or recognition. If you're really willing to donate some money please consider giving them to the Pi-Hole⁠ itself.

- Q: I updated to a version 2025.x.x from a 2024.x.x and nothing works anymore

Yep, this is not my fault. The pihole team redesigned the entire application and changed names of a lot of variables. Please refer to this guide⁠.

- Q: Why doesn't it work on my system?

I don't know, but maybe you can find more details here⁠.

⁠Credits

Thanks to Chris Crowe⁠ for figuring the original (pihole version <= 2024.x.x) installation method out and inspiring this project.