Pi-Hole + Unbound on Docker

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

• Install Unbound directly into the Pi-Hole container
  • 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.
  • With this approach, we can also simplify our Docker networking since macvlan is no longer necessary.

Updates

This image is regularly update with the latest release from the official pi-hole image.

Whenever there is an update for the original pihole image an automatic pull request is opened to implement the update and I do my best to merge the updates quickly.

The workflow file for this can be found in .github/workflows/auto-build-container.yml

This workflow runs when the image tag is updated in pihole-unbound/Dockerfile. I do that semi-manually with the help of the renovate bot. Therefore you may experience some delay whenever there is an update for the original pihole image

Description

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 to the container based on instructions provided directly by the Pi-Hole team.

Setup

1. Create a directory somewhere to set things up, such as /opt/docker/pihole-unbound/.
2. Download/copy the docker-compose.yaml file and put it in this directory.
3. Create a .env file in this directory as well. It will be used to substitute variables for your deployment.

Pi-hole environment variables

Vars and descriptions replicated from the official pihole container:

Variable	Default	Value	Description
TZ	UTC	<Timezone>	Set your timezone to make sure logs rotate at local midnight instead of at UTC midnight.
WEBPASSWORD	random	<Admin password>	http://pi.hole/admin password. Run docker logs pihole | grep random to find your random pass.
FTLCONF_LOCAL_IPV4	unset	<Host's IP>	Set to your server's LAN IP, used by web block modes and lighttpd bind address.
REV_SERVER	false	<"true"|"false">	Enable DNS conditional forwarding for device name resolution
REV_SERVER_DOMAIN	unset	Network Domain	If conditional forwarding is enabled, set the domain of the local network router
REV_SERVER_TARGET	unset	Router's IP	If conditional forwarding is enabled, set the IP of the local network router
REV_SERVER_CIDR	unset	Reverse DNS	If conditional forwarding is enabled, set the reverse DNS zone (e.g. 192.168.0.0/24)
WEBTHEME	default-light	<"default-dark"|"default-darker"|"default-light"|"default-auto"|"lcars">	User interface theme to use.
VIRTUAL_HOST	$FTLCONF_LOCAL_IPV4	<Custom Hostname>	What your web server 'virtual host' is, accessing admin through this Hostname/IP allows you to make changes to the whitelist / blacklists in addition to the default 'http://pi.hole/admin' address

Example .env file in the same directory as your docker-compose.yaml file:

FTLCONF_LOCAL_IPV4=192.168.1.10
TZ=Europe/Copenhagen
WEBPASSWORD=QWERTY123456asdfASDF
REV_SERVER=true
REV_SERVER_DOMAIN=local
REV_SERVER_TARGET=192.168.1.1
REV_SERVER_CIDR=192.168.0.0/16
HOSTNAME=pihole
DOMAIN_NAME=pihole.local
PIHOLE_WEBPORT=80
WEBTHEME=default-light
VIRTUAL_HOST=pihole.box

Running the stack

docker-compose up -d

If using Portainer, just paste the docker-compose.yaml contents into the stack config and add your environment variables directly in the UI.

Configure Pi-Hole

1. Open up Pi-Hole's Dashboard (web interface).

In your web browser, if you're on the host machine, go to http://127.0.0.1/admin/. To access it from other devices on your local network, replace 127.0.0.1 with the LAN IPv4 of the machine running Pi-Hole.

2. Open the Settings menu and navigate to the DNS tab.
3. Make sure all checkboxes in both Upstream DNS Servers panels are unchecked.
4. Check Custom 1 (IPv4) and set its value to 127.0.0.1#5335.
5. Hit Save on the bottom of the page.

You're done! Now, it's up to you to get your network/devices setup to use Pi-Hole.

Troubleshooting

Local devices get no/limited internet when using Pi-Hole as DNS.

Try pinging google.com vs pinging 8.8.8.8. If google.com fails but 8.8.8.8 succeeds, the Pi-Hole's "Allow only local requests" under Settings > DNS > Interface settings isn't accepting your local devices as local devices. Changing this to "Permit all origins" will solve the issue but may introduce security concerns. The root issue is something you will have to investigate yourself but this will help with troubleshooting why Pi-Hole appeared to "break" your internet.

Building the image locally

• Clone this repo to you machine
• Run the commands below

cd docker-pihole-unbound
docker build . -t dev/docker-pihole-unbound:latest

Automatic dev builds with Github Actions

I have setup a Github Aciton that runs on all pull requests that builds and publishes the image configured in the repo. The action can be found in .github/workflows/dev-build.yml. To use this feature please comment your repo and tag me (@aleksanderbl29) and I will run the workflow for you.

Contributors

Thank you to all contributors for help making this project better.