SEC.01
The playbook
The run starts read-only: the recon probes decide what happens next. The steps that follow are adapted to the distribution and state found — a real machine is rarely clean.
- 01reconDocker and the compose plugin present (prerequisite)
- 02reconPi-hole already installed (native or container)? then verify and skip
- 03reconwho holds port 53 and on which address (systemd-resolved on 127.0.0.53?)
- 04reconcurrent server resolver (must keep working)
- 05reconthe requested listen IP exists on an interface
- 06recontime zone
- 07actGenerate the admin passwordverify
- 08actFree port 53 (only if the listen IP is 0.0.0.0)destructiveverify
- 09actWrite /opt/pihole/compose.yamlverify
- 10actRun Pi-holeverify
- 11actDNS respondsverify
- 12actThe web UI respondsverify
SEC.02
What it verifies
Each step ships its own check. The run only moves on when the check passes, so what the recipe reports as done is what is actually on the server.
- 01verifyGenerate the admin passwordVerified by
stat -c %a /opt/pihole/.env - 02verifyFree port 53 (only if the listen IP is 0.0.0.0)Verified by
getent ahosts download.docker.com | head -1 - 03verifyWrite /opt/pihole/compose.yamlVerified by
docker compose -f /opt/pihole/compose.yaml config -q && echo ok - 04verifyRun Pi-holeVerified by
docker inspect -f '{{.State.Health.Status}}' pihole - 05verifyDNS respondsVerified by
dig +short +time=3 @${listen_ip} example.com | head -1 - 06verifyThe web UI respondsVerified by
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:${web_port}/admin/
SEC.03
Guardrails
Non-negotiable instructions the run must respect, whatever it finds on the server.
Never break the server connectivity: no change to the default route, /etc/resolv.conf or the rules that let the Servor agent and the SSH session out. Compare the default route and DNS resolution before/after. If Docker is missing: stop and point to the "Docker Engine" recipe. Never point the server's own resolver at Pi-hole. Never open port 53 publicly (open resolver): listen on a LAN/VPN IP, or 127.0.0.1. An existing native Pi-hole → verify and skip. The admin password is in /opt/pihole/.env: give that path, do not display it.
SEC.04
Variables
What you choose before launching — the recipe fills in the rest.
| Name | Meaning |
|---|---|
| ${listen_ip} | DNS listen IP |
| ${web_port} | Local web UI port |
SEC.05
How a recipe runs in Servor
Servor is zero-knowledge: the platform cannot execute anything on its own. When you launch this recipe, a run reads the reconnaissance, plans the steps and asks for your approval. Each approved command is signed by your browser — with a key the server never sees — then relayed verbatim to the agent, which verifies the signature locally before executing.
search by intent — type “firewall”, get ufw
- 01Read-only reconnaissance before any change
- 02Every command signed by your browser, approved by you
- 03Each step verified before the run moves on, every run kept in the history
SEC.06
Deploy on Servor button
Maintain Pi-hole or a project that needs it? Put this button in your README or on your site: one click and your users install it on their own server.
Dark background
Light background[](https://servor.app/deploy/install-pihole)SEC.07
More networking recipes
- 01TailscaleTailscale mesh VPN: auth key or login link, without touching the server DNS.
- 02WireGuardWireGuard VPN server + a first client, without touching routing. Destructive: network interface.
- 03AdGuard HomeAdGuard Home filtering DNS, local UI. Destructive: may free port 53.
- 04OpenVPNOpenVPN server via the road-warrior script (angristan), first client created. Destructive: network.
- 05DNS resolver (Unbound)Unbound validating (DNSSEC) recursive DNS resolver, on localhost.
Verified recipe
Run this recipe on your server
Connect a server, launch the recipe, and approve each step as Servor executes and verifies it. Free plan, no card required.