Wireguard + Pi-hole + Unbound + Stubby + 🐳
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
FollieHiyuki 546a481a13
README: add note about dhcphelper
2 months ago
etc-dnsmasq.d Add Unbound + Stubby. Update README 2 months ago
etc-pihole Add Unbound + Stubby. Update README 2 months ago
stubby Add Unbound + Stubby. Update README 2 months ago
unbound Add Unbound + Stubby. Update README 2 months ago
Dockerfile Update files 2 months ago
LICENSE Update files 2 months ago
README.md README: add note about dhcphelper 2 months ago
docker-compose.yml Add Wireguard 2 months ago


Pi-hole + 🐳


This repository holds docker template for Pi-hole with Unbound + Stubby on top, running in my home network as both DNS server and DHCP server (using bridge network). Wireguard is included for convenience.

The DHCP part is yanked from @DerFetzer, with some improvements. The Unbound and Wireguard parts are based on Wirehole. You can also check out this gist and the official Unbound guide.


You should change the variables in docker-compose.yml file. If you want to change the default IP addresses of the internal network, remember to also replace the forward address in unbound.conf, and add the new IP range to "access-control" and "private-address" accordingly.

  • Clone this repository
  • Review the content
  • docker-compose up -d
  • Route DNS traffic from your router to the Pi-hole server
  • Turn on Pi-hole's DHCP server and turn off DHCP function in your router
  • Add more gravity lists. firebog.net has some good ones
  • Profit


  • To check whether recursive DNS is working, you can try running these:
# Check Unbound
dig pi-hole.net @ -p 53

# Check Stubby
dig pi-hole.net @ -p 8053

# Check FTLDNS
dig pi-hole.net @ -p 53
  • To display the peer's QR code again, do docker exec -it wireguard /app/show-peer [peer_name].
  • Stubby isn't packaged for Alpine, so I use Voidlinux-musl for now.
  • You can omit the hostname variables for pi-hole and unbound in docker-compose.yml. The pi-hole's one is for the displayed hostname (top right corner) in the web UI. The other one just makes queries logs easier to read.
  • You can also run Docker Pi-hole as your DHCP server using host network or Macvlan network. Check the official documentation.
  • DNSMASQ_LISTENING: all is needed, because Pi-hole will listen on both the host network (for DNS requests), and the subnet br-pihole. This brings some security risks, so make sure to only run this inside your home network, and do not forward port 53 from your router to the Pi-hole server.
  • dhcphelper needs network_mode: host because it has to be seen by clients on your local network. Though it only needs port 67.
  • If you don't like dhcphelper, here is the diff for using ISC DHCP relay instead:


FROM debian:stable-slim
RUN apt update

RUN apt install -y isc-dhcp-relay
EXPOSE 67 67/udp
ENTRYPOINT ["dhcrelay", "-d"]


     build: .
     restart: unless-stopped
     network_mode: "host"
-    command: ["-i", "eth0", "-b", "br-pihole", "-s", ""]
+    command: ["-id", "eth0", "-iu", "br-pihole", ""]
       - NET_ADMIN