Requirements
Hardware, operating system, ports and the one thing that is not optional.
It was written on a Raspberry Pi 5 and tuned for one. Anything that can run a 64-bit Docker image and hold a few gigabytes will do.
Hardware#
| Minimum | Comfortable | Why | |
|---|---|---|---|
| CPU | 2 cores, or amd64 | 4 cores | Ingest is light; the rollup pass is the only burst of work |
| RAM | 1GB | 2GB+ | SQLite page cache is capped at 32MB; the rest is Node |
| Disk | 2GB free | 8GB+ | ~90 days of a busy household is 200–400MB, plus indexes |
| Storage type | SD card | SSD or NVMe | Write amplification: see the note below |
Software#
- Docker. Any recent version with the Compose plugin. The installer offers to install it.
- A resolver. AdGuard Home — already running, or the installer will put it there — on any version with the standard
/controlAPI, which is every version since 0.107.Pi-hole, which must already be running and must be v6 or newer: v6 replaced v5’s PHP endpoints with a session-authenticated REST API, and only the new one is implemented. - A 64-bit OS. Raspberry Pi OS 64-bit, Debian, Ubuntu, or anything else with a modern kernel. 32-bit ARM is not built for.
Ports#
| Port | Used by | Negotiable |
|---|---|---|
| 53/udp, 53/tcp | AdGuard Home, for DNS itself | No. This is the whole point of it |
| 3000 | This dashboard | Yes, --port |
| 3001 | AdGuard Home admin UI | Yes, --agh-port |
| 853, 443 | DoT and DoH, if you enable them in AdGuard Home | Yes |
| Port | Used by | Negotiable |
|---|---|---|
| 53/udp, 53/tcp | Pi-hole, for DNS itself. Already bound before this is installed | Not yours to negotiate |
| 80 or 443 | Pi-hole's own web interface, which is also its API | Pi-hole's setting, not this one's |
| 3000 | This dashboard | Yes, --port |
Only one of these is new. The dashboard adds a port and touches nothing else — it never binds 53, and it reaches Pi-hole over the same HTTP interface you already use.
systemd-resolved already holds port 53, which is the single most common install failure — and the only one that needs a decision from you.Port 53 is the one that causes trouble, because on most modern Linux distributions systemd-resolved is already listening on it. The installer detects this and offers to move its stub listener out of the way; Troubleshooting explains exactly what that changes.
Credentials#
Stored in a .env file at chmod 600 on the box, and sent only to AdGuard HomePi-hole, over the local network.
AdGuard Home takes the same admin username and password you log in with. There is no way to give it read-only access, because AdGuard Home has no concept of one — the credential that reads your query log is also the one that can change your filtering.
Pi-hole v6 has no username: the password alone is exchanged for a session. Generate an application password under Settings → Web interface / API rather than using your web password — it can be revoked on its own without changing the password you type, and it works when 2FA is enabled, which a plain password with TOTP attached does not.
If your Pi-hole has no password at all, leave PIHOLE_PASSWORD unset. The provider will skip the session exchange rather than fail the boot check.