Configuration
Every environment variable, what it defaults to, and when to change it.
Everything is an environment variable, validated at boot. A misconfigured deploy fails loudly at startup rather than at the first query three hours into an ingest run.
Which resolver#
One variable decides the rest. Fill in the block that matches it and leave the other unset: the settings for the resolver you are not using are ignored, and an empty value counts as unset rather than failing the check. The switch in the header is set to AdGuard HomePi-hole, so that is the block shown below.
| Variable | Default | Notes |
|---|---|---|
DNS_PROVIDER | adguard | adguard or pihole. Defaults to AdGuard Home so installs predating the switch keep working untouched |
AdGuard Home#
| Variable | Example | Notes |
|---|---|---|
ADGUARD_URL | http://192.168.1.10:3000 | Full URL with scheme. Trailing slashes are stripped |
ADGUARD_USERNAME | admin | The admin account you log in with |
ADGUARD_PASSWORD | — | Sent only to AdGuard Home, over your LAN |
Pi-hole#
| Variable | Example | Notes |
|---|---|---|
PIHOLE_URL | http://192.168.1.10 | Full URL with scheme. Pi-hole v6 or newer only |
PIHOLE_PASSWORD | — | No username: v6 exchanges the password alone for a session. Prefer an application password from Settings → Web interface / API — it can be revoked on its own and works with 2FA. Omit entirely if your Pi-hole has no password |
There is no PIHOLE_USERNAME, and adding one is not an oversight: v6’s auth endpoint takes a password and returns a session ID, with no account to name.
Storage and retention#
| Variable | Default | Notes |
|---|---|---|
DATABASE_PATH | ./data/queries.db | Inside the container this is /data/queries.db |
RETENTION_DAYS | 90 | Detail older than this is deleted. Rollups survive forever; see Rollups |
Ingest#
| Variable | Default | Notes |
|---|---|---|
INGEST_ENABLED | true | Set false to run the UI against an existing store without polling |
INGEST_POLL_INTERVAL_MS | 5000 | Lower means fresher and more requests; below ~2s buys nothing |
INGEST_PAGE_SIZE | 500 | AdGuard Home silently clamps anything larger, so raising it does nothingPi-hole honours it, so raising it genuinely means fewer round trips on a busy network |
Links and notifications#
| Variable | Default | Notes |
|---|---|---|
PUBLIC_URL | unset | Where this is reachable from your phone. Without it, notification links are relative and resolve to the phone itself |
NOTIFY_ENABLED | true | Set false to stop the rule engine evaluating or sending |
NOTIFY_HISTORY_DAYS | 30 | How long the delivery log is kept |
Where to put them#
Docker Compose reads .env beside the compose file when you use env_file. Running from source, the same file is read by --env-file-if-exists in the npm scripts. Changing anything requires a restart:
cd /opt/elele-dns
sudo nano .env
sudo docker compose up -d # recreates the container with the new environment