Hands-on Lab

Pihole in Docker (DNS Sinkhole)

July 17, 2026 3 min

0 / 8

Cheat sheet

Found it useful? Don't miss the next lab

0:00 / 0:00

We publish port 53 on both TCP and UDP —DNS uses both, UDP for normal queries and TCP when the answer doesn't fit in one datagram— and port 80 for the web panel. TZ puts log timestamps in your timezone, FTLCONF_webserver_api_password sets the panel password (v6 replaced the old WEBPASSWORD), FTLCONF_dns_listeningMode=ALL makes it listen on every interface instead of just localhost inside the container, and FTLCONF_dns_upstreams declares which resolvers to forward unblocked queries to: without that variable, Pi-hole forwards nothing at all.

docker run -d --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -e TZ='Europe/Madrid' -e FTLCONF_webserver_api_password='changeme' -e FTLCONF_dns_listeningMode='ALL' -e FTLCONF_dns_upstreams='1.1.1.1;8.8.8.8' pihole/pihole:2026.07.2

I did it

We confirm the container is healthy, not just running: Pi-hole's built-in health check runs a dig query against itself (pi.hole), so 'healthy' confirms FTL's DNS engine is actually answering queries, not merely that the process started.

timeout 90 bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" pihole 2>/dev/null)" = "healthy" ]; do sleep 2; done; echo healthy'

Gravity is the process that downloads the default blocklist and compiles it into a local database FTL checks on every request. We run it explicitly to make sure the list is fresh before we test blocking, even though the container already downloads it once on first boot.

docker exec pihole pihole -g

I did it

We confirm gravity actually loaded real domains: a six-figure count proves the blocklist database isn't empty, before we trust that a specific domain will get blocked.

docker exec pihole pihole-FTL sqlite3 /etc/pihole/gravity.db "SELECT COUNT(DISTINCT domain) FROM vw_gravity;"

A normal domain, one that isn't on any blocklist, gets forwarded as-is to the upstream resolvers (1.1.1.1 and 8.8.8.8) and comes back with its real IP. This is the baseline we're about to contrast with the next step.

dig +noall +answer +time=5 @127.0.0.1 wikipedia.org A

I did it

doubleclick.net is on the default blocklist —Pi-hole's own documentation uses it as the canonical example— so instead of forwarding the query, FTL answers it itself with 0.0.0.0. The device gets a valid DNS answer, but one that points nowhere: the ad request never even goes out.

dig +noall +answer +time=5 @127.0.0.1 doubleclick.net A

I did it

v6 stores every query in a SQLite database, pihole-FTL.db, instead of the plain-text file older versions used. status=1 means blocked by gravity, status=2 forwarded, and status=3 served from cache: in the output you'll see the doubleclick.net query blocked right next to wikipedia.org forwarded. It's the same data that feeds the panel's Query Log page.

docker exec pihole pihole-FTL sqlite3 /etc/pihole/pihole-FTL.db "SELECT datetime(timestamp,'unixepoch') AS ts, domain, status FROM queries ORDER BY id DESC LIMIT 5;"

I did it

We can't record the web panel in this environment, but we do confirm the server behind it responds: a 200 confirms the login page is reachable on port 80 and gated by the password we set with FTLCONF_webserver_api_password. Behind that login lives the dashboard, showing the exact same figures we just pulled from the command line.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/admin/

I did it

pihole status is the one-line equivalent of glancing at the dashboard's traffic light: it confirms DNS is listening and blocking is enabled, with no need to open a browser or query the database by hand.

docker exec pihole pihole status

I did it

Since this is a throwaway container, we remove it along with its process when we're done: docker rm -f stops the container if it's still running and deletes it in the same step. We never created a named volume, so there's nothing persistent left to clean up beyond that.

docker rm -f pihole

I did it

We confirm the cleanup: the name filter returns no lines, proving the pihole container no longer exists, neither running nor stopped.

docker ps -a --filter name=pihole --format '{{.Names}}'

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

What Pi-hole actually does

Pi-hole isn’t a browser ad blocker: it’s a DNS resolver. Every device on your network that points to it as its DNS server runs each query through gravity, the compiled list of ad and tracking domains. If the domain is on the list, Pi-hole answers with 0.0.0.0 instead of forwarding the question to the internet; if it isn’t, it forwards it to a real resolver (in this lab, 1.1.1.1 and 8.8.8.8) and hands you back the genuine answer. That’s why blocking works the same in a browser, a phone app, or a smart TV’s firmware: it doesn’t depend on an extension installed per device.

Why the container needs the FTLCONF_* variables

Version 6 replaced environment variables like WEBPASSWORD with the FTLCONF_ prefix, which maps directly onto FTL’s own configuration keys. In this lab we set the panel password with FTLCONF_webserver_api_password, open the DNS listener to every interface with FTLCONF_dns_listeningMode=ALL, and, something people often forget, declare the upstream resolvers with FTLCONF_dns_upstreams: without that variable Pi-hole won’t forward anything at all.

Pairs well with the rest of your self-hosted stack

We already covered how to install Pi-hole with Docker step by step, and if you want an alternative with built-in DNS-over-HTTPS, check out how to install AdGuard Home with Docker. You’ll find more self-hosted infrastructure pieces in the Tools category and the rest of our fully verified, step-by-step guides in the hands-on labs.

Official references

For the full breakdown of every environment variable, see the official docker-pi-hole repository, for the exact behavior of NULL blocking mode see the FTLDNS documentation, and for the published image versions see the Docker Hub repository.

FAQ

What is Pi-hole and how does it block ads at the DNS level?

Pi-hole is a DNS resolver that acts as a sinkhole: it checks every query against its blocklists (gravity) and, on a match, answers it itself instead of forwarding it to the internet. The device never actually reaches the ad server, so the ad never loads, in any app or device using that DNS.

Why does a blocked domain resolve to 0.0.0.0 instead of failing?

0.0.0.0 is Pi-hole's default blocking mode, called NULL: it's an address no real service uses, so the browser or app's request fails instantly instead of hanging until a timeout expires. It's a fast, predictable answer, not a network error.

Do you need to change the router's DNS to block ads on every device?

For a genuinely network-wide block, yes: you point the router's DNS at the Pi-hole container's IP and every device that connects inherits it automatically over DHCP. In this lab we publish port 53 and query it directly with dig, since the container doesn't have a real router network to point at.

Can I see the query log without opening the web panel?

Yes: Pi-hole v6 stores every query in a SQLite database (pihole-FTL.db) that you can read with pihole-FTL sqlite3 from the command line, including each query's status (blocked, forwarded, or served from cache). The web panel just visualizes that same data.

Cheat sheet

docker run -d --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -e TZ='Europe/Madrid' -e FTLCONF_webserver_api_password='changeme' -e FTLCONF_dns_listeningMode='ALL' -e FTLCONF_dns_upstreams='1.1.1.1;8.8.8.8' pihole/pihole:2026.07.2

```
docker exec pihole pihole -g
```

dig +noall +answer +time=5 @127.0.0.1 wikipedia.org A

dig +noall +answer +time=5 @127.0.0.1 doubleclick.net A

docker exec pihole pihole-FTL sqlite3 /etc/pihole/pihole-FTL.db "SELECT datetime(timestamp,'unixepoch') AS ts, domain, status FROM queries ORDER BY id DESC LIMIT 5;"

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/admin/

```
docker exec pihole pihole status
```
```
docker rm -f pihole
```

Found it useful? Don't miss the next lab

Subscribe to the newsletter

What Pi-hole actually does

Why the container needs the FTLCONF_* variables

Pairs well with the rest of your self-hosted stack

Official references

FAQ

What is Pi-hole and how does it block ads at the DNS level?

Why does a blocked domain resolve to 0.0.0.0 instead of failing?

Do you need to change the router's DNS to block ads on every device?

Can I see the query log without opening the web panel?

Cheat sheet