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:

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.