mokhtar
22abcd9b7b
flake.nix fetches the release tarballs and carries their SRI hashes in a generated block. The cut tool builds the release locally with the toolchain gates.yml pins, in a normalized nine-variable environment, writes the hashes into flake.nix, and commits it with build.zig.zon as the single bump commit. The package job verifies the pins on the bump commit and the publish job verifies them again on the tag, before anything is uploaded. The tarballs are written by dist_stage (std.tar.Writer, flate gzip) instead of the runner's tar and gzip, and -ffile-prefix-map keeps checkout paths out of the C objects; two checkouts at different absolute paths produce byte-identical archives. nxdns version, /api/version and the admin footer report the version only: the bump commit cannot know its own sha.
nxdns documentation
The pages are split by what you are trying to do, following Diátaxis. 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 | Someone who has never run nxdns | You want to learn what it does by making it work once |
| How-to guides | An operator with a job to do | You know what you want and need the steps |
| Reference | Anyone who needs an exact answer | You want a field, a flag, a route or an exit code |
| Explanation | Anyone deciding or debugging | You want to know why it works the way it does |
Tutorial
A lesson, not a procedure: one path with one outcome, on a scratch directory you can delete afterwards.
- tutorial/first-run.md — build nxdns, resolve a name, block a domain from a real blocklist, open the web interface, stop cleanly.
How-to guides
Steps for a goal you already have. They assume you know what nxdns is.
- 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 — a real install as a system service, including the Raspberry Pi 5 aarch64 binary.
- how-to/install-with-docker.md — the published container image and the compose file.
- how-to/install-with-nix.md — the flake input pinned to a release tag, and Renovate for tag bumps.
- how-to/upgrade.md — move to a new release without losing state.
- 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 — serve encrypted DNS with certificates.
- how-to/set-up-admin-authentication.md — put a password on the web interface and the API.
- how-to/back-up-and-restore.md — export and import the configuration, and what to copy.
- how-to/measure-performance.md — run the benchmark harness on your own hardware.
Reference
Descriptions of what is there. No procedures, no advice.
- reference/configuration.md — every configuration section, field, default and range.
- reference/api.md — every REST route, authentication and the event stream.
- reference/cli.md — the six subcommands, every flag, every exit code.
- reference/files-and-directories.md — the data directory layout and file modes.
- reference/query-log-lifecycle.md — how
querylog.dbis versioned, migrated, backed up and, rarely, recreated. - reference/performance.md — the targets and the measured numbers.
Explanation
Background. Nothing here is needed to operate nxdns; it is here so the decisions are inspectable.
- explanation/architecture.md — the module map and the design it comes from.
- 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 — 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 and ../specs/.