milestone 14: build, package, sign and publish releases

README.md

@@ -20,14 +20,30 @@ you what asked for what.
 - Prometheus-style `/metrics`, per-client rate limiting, disk-full
   self-protection
 
+## Install
+
+**No release exists yet.** This repository has no tags, nothing has been
+published to <https://git.mial.net/mokhtar/nxdns/releases>, and no container
+image has been pushed. Every release URL on this page and in the how-to guides
+is a 404 today, and `docker pull` finds nothing. Until the first tag ships,
+building from source is the only way to get nxdns.
+
+What a tag will publish, once one exists: five assets — two static musl
+tarballs (`nxdns-<version>-x86_64-linux-musl.tar.gz`,
+`nxdns-<version>-aarch64-linux-musl.tar.gz`), `IMAGE-DIGEST.txt` naming the
+multi-architecture container image by digest, `SHA256SUMS.txt` covering those
+three files, and `SHA256SUMS.txt.asc`, a detached OpenPGP signature over the
+checksum file. Verify what you downloaded before you run it:
+[docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md), which also
+says what that signature does and does not prove.
+
 ## Quickstart (docker compose)
 
-Build the binary and image, seed a minimal configuration, start it:
+Seed a minimal configuration and start the published image. This is what the
+first release will make possible; it does not work today, because there is no
+image in the registry to pull:
 
 ```sh
-(cd web && npm ci && npm run build)
-zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
-
 cd deploy/docker
 mkdir -p etc-nxdns
 cat > etc-nxdns/config.zon <<'EOF'
@@ -37,11 +53,15 @@ cat > etc-nxdns/config.zon <<'EOF'
     .web = .{ .password = "choose-a-real-password" },
 }
 EOF
-docker compose up -d
+NXDNS_VERSION=<version> docker compose up -d
 ```
 
-DNS is on port 53, the web UI on <http://localhost:8080>. The config file
-seeds the database on first boot only; from then on the database is the
+The compose file defaults to `:latest`; pin a version for anything you intend
+to keep running. To run it before a release exists, build the image yourself and
+name it — `NXDNS_IMAGE=nxdns docker compose up -d` — as
+[docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md)
+describes. DNS is on port 53, the web UI on <http://localhost:8080>. The config
+file seeds the database on first boot only; from then on the database is the
 truth and changes go through the UI, the API, or `nxdns export` /
 `nxdns import`. Full install instructions, including the systemd path and
 the Pi 5 recipe, are in
@@ -57,11 +77,32 @@ the web UI). C dependencies (SQLite, mbedTLS) are vendored and built by
 ```sh
 (cd web && npm ci && npm run build)          # web UI -> web/dist
 zig build -Dweb-dist=web/dist                # native binary -> zig-out/bin/nxdns
-zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
-                                             # static x86_64 + aarch64 musl binaries
 zig build test --summary all                 # unit tests
 ```
 
+The release artifacts come out of the same build graph, so the whole release
+build runs on a laptop exactly as it runs on the CI runner:
+
+```sh
+(cd web && npm ci && npm run build)                # required: dist refuses the placeholder
+VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
+zig build dist -Dversion-string="$VERSION" -Dgit-commit=$(git rev-parse HEAD) \
+    -Dweb-dist=web/dist -Doptimize=ReleaseSafe     # tarballs -> zig-out/dist/
+zig build verify-dist -Dversion-string="$VERSION" -Dgit-commit=$(git rev-parse HEAD) \
+    -Dweb-dist=web/dist -Doptimize=ReleaseSafe     # the release checks
+```
+
+The version comes from `build.zig.zon` because `verify-dist` asserts the two
+agree; a tag sets both.
+
+That is not a claim that your tarball will hash the same as a published one.
+Nothing in this project measures whether two builds of the same commit on two
+different machines land on the same bytes, so no document here describes the
+build as reproducible. The gate that would settle it is a recorded deferral —
+`specs/milestone-14.md` ruling 12 — and
+[docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md) explains what
+a matching or differing hash is worth in the meantime.
+
 ## Documentation
 
 Start at [docs/README.md](docs/README.md), which splits the documentation
@@ -71,6 +112,8 @@ into a tutorial, how-to guides, reference and explanation.
   a name, block a domain, on a scratch directory
 - [docs/how-to/install-with-systemd.md](docs/how-to/install-with-systemd.md) —
   a real install, including the Raspberry Pi 5
+- [docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md) — checking
+  the hashes and the signature before you install
 - [docs/reference/configuration.md](docs/reference/configuration.md) — every
   configuration field
 - [docs/reference/api.md](docs/reference/api.md) — REST API, auth and SSE
@@ -80,3 +123,14 @@ into a tutorial, how-to guides, reference and explanation.
   map and design
 - [PLAN.md](PLAN.md) and [specs/](specs/) — scope, design decisions and
   per-milestone contracts
+
+## Licence
+
+Copyright (c) 2026 Mokhtar Mial. nxdns is licensed under the European Union
+Public Licence v. 1.2 (`EUPL-1.2`); the full text is in [LICENSE](LICENSE).
+
+Every released tarball and image carries a `THIRD-PARTY-NOTICES` file assembled
+from the reviewed inventory in [licenses/](licenses/), which covers what the
+artifacts actually contain: musl, the Zig runtime, SQLite, Mbed TLS and its
+vendored Everest and p256-m code, and the JavaScript and CSS bundled into the
+admin UI.