Skip to content

Pi-hole ​

Pi-hole filters DNS in a Docker container on VM 103. UniFi continues to provide routing and DHCP; do not enable DHCP inside this deployment.

Prepare the guest using the host setup guide. Host-specific AI commands and private recovery details are in Pi-hole · Internal Operations.

See DNS Resolution for the DHCP settings, upstream resolver path, and service-name checks.

Access and configuration ​

SettingThis homelab
Host address10.120.40.103
Domainpi-hole.home.rwk.me
Normal accesshttps://pi-hole.home.rwk.me
Direct accesshttp://10.120.40.103:80
Project directory/docker/pihole

For another homelab, use your own host address, domain, timezone, paths, and network policy. The addresses above describe internal access; the dashboard does not require a public router port forward.

Create the project ​

Run as a deployment account with Docker access on the prepared guest:

sh
sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0750 /docker/pihole
cd /docker/pihole

Create compose.yaml with the following configuration. It is a documented example of the repository's pinned deployment, not a second deployment source file:

yaml
services:
  pihole:
    image: pihole/pihole:2026.10.0
    container_name: pihole
    hostname: pihole
    environment:
      TZ: ${TZ}
      FTLCONF_webserver_api_password: ${FTLCONF_webserver_api_password}
      FTLCONF_dns_listeningMode: ALL
      FTLCONF_dns_upstreams: ${FTLCONF_dns_upstreams}
    volumes:
      - ./etc-pihole:/etc/pihole
    ports:
      - "${SERVER_IP}:53:53/tcp"
      - "${SERVER_IP}:53:53/udp"
      - "${SERVER_IP}:80:80/tcp"
    restart: unless-stopped

Create .env alongside it:

dotenv
SERVER_IP=10.120.40.103
TZ=America/Chicago
FTLCONF_webserver_api_password=replace-with-generated-password
FTLCONF_dns_upstreams=1.1.1.1;1.0.0.1

Replace blank secrets and example credentials before starting. SERVER_IP must be an address assigned to the Docker host. Preserve existing keys and data when updating an installation. Protect the file with chmod 600 .env and keep it out of Git.

Set an independent generated administration password in FTLCONF_webserver_api_password. FTLCONF_dns_upstreams is a semicolon-separated list of external upstream resolvers. The Docker listening mode is ALL so container networking can receive forwarded DNS traffic; restrict access with your network policy rather than exposing it to the internet.

Create etc-pihole on the VM's local disk before deployment. Check that TCP/UDP 53 and TCP 80 are not already occupied by another service on the intended host address.

Start and verify ​

Run only this Compose project:

sh
cd /docker/pihole
docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 180
docker compose ps
docker compose logs --tail=100 pihole

Keep logs private. Do not rerun the base guest provisioner to install or update one service; it upgrades the host and restarts Docker.

Configure DNS and HTTPS ​

Make pi-hole.home.rwk.me resolve to Nginx Proxy Manager (10.120.40.101 in this lab). Add a proxy host:

SettingValue
Domainpi-hole.home.rwk.me
Schemehttp
Backend10.120.40.103
Port80
WebSocketsNot required
CertificateA certificate covering pi-hole.home.rwk.me
Force SSL / HTTP/2Enabled

Use your own domain and certificate on another homelab. Apply a LAN/VPN access list appropriate to your users. A proxy access list does not restrict clients connecting directly to a backend port; use network filtering when the backend must be proxy-only.

Check both paths:

sh
curl --fail --silent --show-error --output /dev/null http://10.120.40.103:80/admin/
curl --fail --silent --show-error --output /dev/null https://pi-hole.home.rwk.me/admin/

Add the HTTPS health endpoint to Uptime Kuma, using TLS validation and a suitable check interval. Monitoring on the same VM cannot independently report that VM's outage.

Configure filtering ​

Open /admin/ on the dashboard and sign in with the configured application password. Keep the existing general-purpose subscriptions and add feeds appropriate to your tolerance for blocking. This lab uses balanced HaGeZi Multi NORMAL and Threat Intelligence Feeds Mini alongside its original lists:

text
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt
https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/adblock/multi.txt
https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/adblock/tif.mini.txt

Add the URLs as subscribed deny lists and rebuild Gravity. More aggressive telemetry feeds can break vendor features. When troubleshooting a blocked legitimate service, use Tools → Search Adlists to identify the responsible rule and add the narrowest necessary allow entry. Keep connectivity checks such as ping.ui.com resolvable.

The private runbook owns this lab's additional subscriptions and exact telemetry policy; the repository retains their source list files. Do not assume every client network should receive identical filtering.

Before changing DHCP, verify resolution from the DNS VM and each intended client network:

sh
dig @10.120.40.103 example.com A +time=2 +tries=1
dig @10.120.40.103 example.com A +tcp +time=2 +tries=1

Test an intentionally blocked domain as well. Configure the desired UniFi networks to advertise 10.120.40.103 as DNS, renew a representative client's lease, and verify its assigned resolver and actual DNS behavior. Do not advertise a public resolver alongside Pi-hole if filtering must apply: clients can select it and bypass the filter.

Maintenance and recovery ​

Container replacement briefly interrupts DNS. Back up consistent application state and preserve the configuration before updating. The lab DNS runner archives stopped data, starts the replacement, and checks DNS over UDP and TCP plus HTTP. Verify filtering subscriptions and exact rules after a restore, then retest routed client networks before restoring normal DHCP DNS assignments.

The deployed files remain in the private homelab source directory. Keep these instructions aligned with source changes. Review release notes and preserve a recovery point before updating pinned images. After maintenance, repeat the checks and verify the main application function.