From 0affaede81c436d972d04be84009261c9d1adcc4 Mon Sep 17 00:00:00 2001 From: Wynne Pirini Date: Fri, 16 Oct 2026 14:46:24 +1300 Subject: [PATCH] docs(ns8): :latest is amd64-only, not unusable The README said :latest was "currently unusable" because no module release had been cut. That stopped being true and then became misleading in the other direction: a release HAS been cut, so :latest resolves, installs and works on an amd64 node. Saying it is unusable would send an amd64 admin hunting for a problem they do not have, while saying nothing would send an arm64 admin into a hard failure at add-module. The accurate statement: :latest, :0.10 and :0.10.1 all point at the same amd64-only manifest. Works on amd64, fails on arm64. :edge is multi-arch and correct on both. The :edge recommendation stays until a real multi-arch release lands. Also explains why, which the old wording got wrong: that release predates the multi-arch publishing work, so each architecture was pushed straight onto the public tags rather than assembled into a manifest list. And labels arm64 support honestly. The image builds for both architectures and the manifest lists both, and the arm64 app binary has been executed and works (keyvault, all migrations, HTTP served). But that was under CPU emulation, so arm64 is NOT verified on real hardware. Nothing has run on a physical arm64 machine or an arm64 NS8 node, and emulation cannot show native kernel behaviour or performance. Stating that here is the point. --- packaging/ns8/README.md | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/packaging/ns8/README.md b/packaging/ns8/README.md index 8ed8de3b..39e93069 100644 --- a/packaging/ns8/README.md +++ b/packaging/ns8/README.md @@ -37,12 +37,20 @@ Replace `calnode` with the actual registry namespace if you built your own image (see Development). The command prints the instance name, usually `ns8-calnode1`. -> **Use `:edge`, not `:latest`.** This module has not had a release tag yet, so -> `:latest` still points at the first build, which predates the fixes for a -> missing `create-module` action, non-executable action scripts and an -> invalid schema pattern. That build fails at `add-module`. `:latest` becomes -> usable at the next module release, at which point a pinned version tag -> (`ghcr.io/calnode/ns8-calnode:0.10.2`, say) is the better thing to install. +> **Use `:edge`, not `:latest`.** A release has been cut, but `:latest`, +> `:0.10` and `:0.10.1` all point at the **same amd64-only** image. It installs +> and works on an amd64 node, and **fails on an arm64 node** (a Raspberry Pi, for +> example), which cannot pull it. +> +> That release predates the multi-arch publishing work, so each architecture was +> pushed straight onto the public tags instead of being assembled into one +> manifest list. `:edge` is a proper multi-arch image and is correct on both. +> +> When the next module release lands, `:latest` will be multi-arch too, and a +> pinned version tag (`ghcr.io/calnode/ns8-calnode:0.11.1`, say) becomes the +> better thing to install. CI now asserts that every published tag really is a +> multi-arch index before a release is allowed to pass, so this specific +> breakage cannot recur silently. Then configure it with your public hostname: @@ -147,15 +155,27 @@ tag pushes, mirroring the app tags in `docker-publish.yml`: - push a `vX.Y.Z` tag pushes module `:X.Y.Z`, `:X.Y` and `:latest`, running app `:X.Y.Z`, so a module release always runs the matching app release -Because `:latest` only moves on a release tag, and no module release has been -cut yet, `:latest` is currently unusable (see Install). Use `:edge` until the -first module release lands. +Because `:latest` only moves on a release tag, and the one release so far was +cut before the multi-arch work landed, `:latest` is currently amd64-only. Use +`:edge` until the next module release (see Install). Every published module tag is a **multi-arch** manifest (amd64 + arm64). NS8 runs modules as rootless containers on the node, so a single-arch image would install on amd64 and fail on arm64. CI builds each arch to a private `:build-` tag and only then assembles the public tags, so an interrupted -release cannot publish a single-arch image under a version tag. +release cannot publish a single-arch image under a version tag. After +assembling, CI reads the published tag back out of the registry and asserts it +really is a two-arch index with coherent per-arch labels, so a publish that +silently produced a single-arch tag fails the release rather than shipping. + +**arm64 status, stated honestly.** The image is built for both architectures and +the manifest lists both, so an arm64 node can install it. The arm64 app binary +has been executed and works: it generated its encryption key, applied all +database migrations, and served HTTP. That was under CPU emulation, though, so +**arm64 is not yet verified on real hardware.** Nothing here has run on a +physical arm64 machine or on an arm64 NS8 node, and emulation cannot show native +kernel behaviour or performance. Treat arm64 as untested until it has been +exercised on a device. To build locally on a machine with podman and buildah, from this directory: