Manage local DNS using Pihole
One of the most important things to do when setting up a homelab is to get a local DNS solution in place. Setting this up allows you to refer to services using a domain name. Whether it’s backend communication between services or accessing the front-end of a service through your browser. In addition, there are other benefits that you gain as you use Pihole like ad-blocking and dhcp. For this example, we will only be using and setting up the DNS functionality, but feel free to use this as a dhcp server as well.
The code I will be referring to in this post is located here: https://github.com/nateleavitt/pihole-docker
Prereqs
- You need a server (or vm) that will act as your DNS server
- This server needs to have a static ip address (internal)
I use proxmox to setup/manage all my vm’s for my local network.
Configuration
Disable host DNS
By default Ubuntu and most linux distros come with a DNS service on by default. To enable Pi-hole as your main DNS server you will need to disable the DNS service on your distro. Do the following in Ubuntu:
1
2
3
4
5
6
7
8
# edit resolved.conf
edit /etc/systemd/resolved.conf
# update this setting DNSStubListener=yes to the following
DNSStubListener=no
# restart systemd resolved
sudo systemctl restart systemd-resolved
From there port 53 should no longer be used.
Environment
This code base uses a .env file for settings. You can use this method or another way that you would like. I have included the .env.example file that you can rename to .env. It also needs to exist wherever you are starting the docker-compose file. You will need to update the WEBPASSWORD that is used when logging into the admin interface. I will provide an alternative way to set the password below if you don’t want to include it in the .env file.
1
2
3
4
# .env.example file
WEBPASSWORD=your-password-here # optional
TZ=America/Phoenix
PIHOLE_DNS_=1.1.1.1;1.0.0.1
Start the Container
To start the Pi-hole service
1
docker compose up -d
From there you should be able to access your pi-hole service on port 8053 of the server. Example: http://192.168.1.10:8053.
Alternative Way to Set Password
If you remove the WEBPASSWORD line in the .env file, Pi-hole will auto generate a password for you. It’s viewable in the logs of the container. So after starting it, view the logs with docker compose logs. You should see the password which was auto generated. Then to change it you need to run a command inside the container. You can do that with the following
1
2
3
4
5
6
7
8
# get the container id of pihole
docker ps
# attach to the container
docker exec -it id-of-the-container bash
# then run the following command
pihole -a -p
You should now be able to setup and add DNS entries in the admin interface of Pi-hole, along with other add-blocking abilities if desired.