mokhtar/nxdns
1
0
Fork 0
Code Pull Requests Actions Packages Releases 25 Activity

docs: rewrite for people running nxdns; query-history refusals name their remedy and a refused start gives no wrong hints

Browse Source
This commit is contained in:
mokhtar
2026-10-21 17:03:00 +02:00
parent fbc8fd7882
commit c21e5a9542
31 changed files with 1186 additions and 3877 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+14 -38
View File
@@ -1,52 +1,28 @@
# nxdns documentation
The pages are split by what you are trying to do, following [Diátaxis](https://diataxis.fr/). Each page serves one of four purposes, and knowing which one you want is the fastest way to the right page.
| Mode | For | Read it when |
| --- | --- | --- |
| [Tutorial](#tutorial) | Someone who has never run nxdns | You want to learn what it does by making it work once |
| [How-to guides](#how-to-guides) | An operator with a job to do | You know what you want and need the steps |
| [Reference](#reference) | Anyone who needs an exact answer | You want a field, a flag, a route or an exit code |
| [Explanation](#explanation) | Anyone deciding or debugging | You want to know why it works the way it does |
New to nxdns? Start with [Get started](tutorial/get-started.md). It runs nxdns from a scratch directory and blocks a real ad domain, and you can delete everything afterwards.
## Tutorial
A lesson, not a procedure: one path with one outcome, on a scratch directory you can delete afterwards.
- [tutorial/first-run.md](tutorial/first-run.md) — build nxdns, resolve a name, block a domain from a real blocklist, open the web interface, stop cleanly.
- [Get started](tutorial/get-started.md) — download nxdns, resolve a name, add a blocklist and watch it block, then clean up.
## How-to guides
Steps for a goal you already have. They assume you know what nxdns is.
- [how-to/verify-a-release.md](how-to/verify-a-release.md) — check the signature and the checksums before you run anything, and what they prove.
- [how-to/install-with-systemd.md](how-to/install-with-systemd.md) — a real install as a system service, including the Raspberry Pi 5 aarch64 binary.
- [how-to/install-with-docker.md](how-to/install-with-docker.md) — the published container image and the compose file.
- [how-to/install-with-nix.md](how-to/install-with-nix.md) — the flake input pinned to a release tag, the `services.nxdns` NixOS module, and Renovate for tag bumps.
- [how-to/upgrade.md](how-to/upgrade.md) — move to a new release without losing state.
- [how-to/troubleshoot.md](how-to/troubleshoot.md) — what to do when it does not answer, does not block, or will not start.
- [how-to/enable-doh-and-dot.md](how-to/enable-doh-and-dot.md) — serve encrypted DNS with certificates.
- [how-to/set-up-admin-authentication.md](how-to/set-up-admin-authentication.md) — put a password on the web interface and the API.
- [how-to/back-up-and-restore.md](how-to/back-up-and-restore.md) — export and import the configuration, and what to copy.
- [how-to/measure-performance.md](how-to/measure-performance.md) — run the benchmark harness on your own hardware.
- [Verify a release](how-to/verify-a-release.md) — check the signature and checksums before you run anything.
- [Install with systemd](how-to/install-with-systemd.md) — a system service on Linux, including a Raspberry Pi.
- [Install with Docker](how-to/install-with-docker.md) — the published image with Docker Compose.
- [Install with Nix](how-to/install-with-nix.md) — the flake and its `services.nxdns` NixOS module.
- [Upgrade](how-to/upgrade.md) — move to a new release, and back if you must.
- [Enable DoH and DoT](how-to/enable-doh-and-dot.md) — serve encrypted DNS to your devices.
- [Set up admin authentication](how-to/set-up-admin-authentication.md) — put a password on the web interface.
- [Back up and restore](how-to/back-up-and-restore.md) — export the configuration and load it back.
## Reference
Descriptions of what is there. No procedures, no advice.
- [reference/configuration.md](reference/configuration.md) — every configuration section, field, default and range.
- [reference/api.md](reference/api.md) — every REST route, authentication and the event stream.
- [reference/cli.md](reference/cli.md) — the six subcommands, every flag, every exit code.
- [reference/files-and-directories.md](reference/files-and-directories.md) — the data directory layout and file modes.
- [reference/query-log-lifecycle.md](reference/query-log-lifecycle.md) — how `querylog.db` is versioned, migrated, backed up and, rarely, recreated.
- [reference/performance.md](reference/performance.md) — the targets and the measured numbers.
- [Configuration](reference/configuration.md) — every setting and list, with defaults and allowed values.
- [Command line](reference/cli.md) — every command, flag and exit code.
- [Files and directories](reference/files-and-directories.md) — what nxdns keeps where, and the query history database.
## Explanation
Background. Nothing here is needed to operate nxdns; it is here so the decisions are inspectable.
- [explanation/architecture.md](explanation/architecture.md) — the module map and the design it comes from.
- [explanation/configuration-model.md](explanation/configuration-model.md) — why there are two authority modes, how each one is selected, and what each is for.
- [explanation/performance-and-testing.md](explanation/performance-and-testing.md) — why the targets exist, why CI does not gate on them, and what the hermetic tests do and do not prove.
Scope and per-milestone contracts live outside this directory, in [../PLAN.md](../PLAN.md) and [../specs/](../specs/).
- [The configuration model](explanation/configuration-model.md) — database mode and file mode, and which to choose.