Last updated on 5 April 2025
Host
Drop the compose below into your Project YAML section.
YAML
services:
pihole:
image: pihole/pihole:latest
container_name: pihole-host
cap_add:
- CAP_NET_RAW
- CAP_NET_BIND_SERVICE
- CAP_CHOWN
# - CAP_NET_ADMIN #uncomment if you want to use DHCP
- CAP_SYS_NICE
- CAP_SYS_TIME
environment:
- PIHOLE_UID=1234 #CHANGE_TO_YOUR_UID
- PIHOLE_GID=65432 #CHANGE_TO_YOUR_GID
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- FTLCONF_webserver_api_password=YOURPASSWORD
- FTLCONF_webserver_port=8000
- DNSMASQ_USER=pihole
volumes:
- /volume1/docker/pihole:/etc/pihole
network_mode: host
labels:
- com.centurylinklabs.watchtower.enable=false
restart: unless-stoppedWe are now changing some settings to the YAML based on your User IDs and Timezone etc
| Section | Explanation |
|---|---|
| PIHOLE_UID= | This UID is the one you obtained when setting up your dockerlimited user in the earlier guide at the start of the page. This tells Pi-hole to run under this user rather than root and gives it access to the folders we created. |
| PIHOLE_GID= | As per the above this line will be the GID you obtained earlier. |
| TZ= | You will need to change this line to your own timezone code – you can find the correct list of ones to use on wikipedia.org/wiki/List_of_tz_database_time_zones |
| FTLCONF_webserver_ api_password= | Change this to the password you would like to use for the Web UI |
| FTLCONF_webserver_port | I have used port 8000 as the default you can amend this if you wish, if you do amend the port keep this in mind when you access the UI later. |
You can now jump ahead to Page 5 for the final configuration.
how can we update the FTLCONF_webserver_
api_password ?
Hey check out the official docs for full sets of variables, but this is set exactly as you put
– FTLCONF_webserver_api_password=’THIS IS MY PASSWORD’
https://docs.pi-hole.net/docker/configuration/#environment-variables
Does this automatically install Unbound? I used 127.0.0.1#5335 as my Custom DNS Server, but I get a connection error:
CONNECTION_ERROR Connection error (127.0.0.1#5335): TCP connection failed (Connection refused)
I’m also getting this:
DNSMASQ_WARN dnsmasq warning:
Maximum number of concurrent DNS queries reached (max: 150)
Hey Rod – I just realised my left menu still say Unbound in the link – I actually removed the Unbound element from the guide as it was causing my trouble than its worth. So you need to set it up independently
Were you still planning to add Unbound to the guide later? Was keeping this page bookmarked out of interest for that. Your guides were very helpful when I first started into self-hosting. Thank you so much for sharing your expertise!
I am not sure why, but it seemed to cause lots of random issues for people. I just hunted back through our Pi-hole megathread on Discord as Muiz had a working compose it includes Redis for local caching of queries. You need to place the config files in the right folders
https://paste.drfrankenstein.co.uk/?2dab3f135acedfd0#6k2P2epCToLQB1Hn6fpeFRKEc3MKBJYVaqVoupD6e57A
https://drfrankenstein.co.uk/wp-content/uploads/2025/02/unbound.conf /docker/unbound/data
https://drfrankenstein.co.uk/wp-content/uploads/2025/06/cachedb.conf /docker/unbound/
Just my 2c…
After a lot of testing myself I found out that the only stable and solid solution to use PiHole as a recursive DNS server using docker is by concentrating on the following docker image:
https://github.com/mpgirro/docker-pihole-unbound/blob/main/README.md
So I would suggest to try this one and provide a guide for this image. Really a good and stable solution, much better than using different PiHole and Unbound images in the same project.
OK good to know – will add to the reading list 🙂