Skip to content

docs(ns8): correct the install guidance and declare data handling - #156

Merged
shockalotti merged 1 commit into
mainfrom
docs/ns8-module-docs-and-metadata
Oct 21, 2026
Merged

shockalotti merged 1 commit into
mainfrom
docs/ns8-module-docs-and-metadata

Conversation

@shockalotti

@shockalotti shockalotti commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Docs only. packaging/ns8/README.md and packaging/ns8/ui/public/metadata.json, nothing else. No behaviour change: the only file anything loads at runtime is metadata.json, which the Apps UI reads.

What was wrong

The install instructions were actively costing installs. The README opened with "Use :edge, not :latest", warning that :latest was amd64-only and would fail on an arm64 node. That stopped being true when 0.11.1 shipped: 0.11.1, 0.11 and :latest are all the same multi-arch index, verified again for this PR. We were steering people away from the stable tag and onto an unreleased build, on the strength of a warning that had already been fixed. It appeared twice, once in Install and once in Development.

Now that :latest is safe, the recommendation is a pinned tag. That tells you what you are running, and makes an update deliberate rather than "whatever main published overnight". :edge is described as what it actually is: the unreleased build.

"How it works" was wrong about the app image. It said the module runs ghcr.io/calnode/calnode:latest. It actually runs the image named by the module's org.nethserver.images label, which is the matching app release. That has been the case for every release since the label scheme landed, so the description was wrong the whole time.

Two dead links in metadata.json. code_url pointed at github.com/calnode/ns8-calnode, which does not exist and returns 404; the module lives in the monorepo. documentation_url pointed at the repository root rather than at any documentation. documentation_url now points at this README, which is the administrator documentation, and code_url at the monorepo.

Added: a Data and privacy section

What is stored, that the encryption key lives in the cluster state and is never transmitted, that nothing phones home. And honestly, that mail goes through whatever SMTP provider the operator configures, and that cluster backup hands an encrypted copy of the database plus its key to whatever backup destination is configured.

That last part is the one worth writing down. Both are true and both are operator choices, but neither is obvious, and someone reading this before pointing backups at a third party should not have to infer it. This section is what terms_url points at, which is what the NS8 review looks for.

Verification

  • assert-multiarc.py --pair --expect-app-tag 0.11.1 over 0.11.1, 0.11, latest: PASS, confirming the multi-arch claim the corrected README now makes.
  • Every URL in the README and metadata.json checked, all resolve. Two apparent failures are false positives: book.example.com is a placeholder, and docs.weblate.org returns 403 to HEAD from bots.

Not in this PR

Clone support is #157, deliberately separate so that an untested behaviour change does not hold up a documentation fix. The README section it adds lives in that PR, which is why these two touch the same file and stack rather than merge independently.

Three fixes to the module README, all of which would have cost us installs or
credibility if a reviewer had read them.

The install section told people to use :edge and not :latest, warning that
:latest was amd64-only and would fail on an arm64 node. That stopped being true
when 0.11.1 shipped: 0.11.1, 0.11 and :latest are all the same multi-arch
index. The README was still steering people away from the stable tag and onto an
unreleased build, on the strength of a warning that had already been fixed. Now
that :latest is safe, the recommendation is a pinned version tag, because that
tells you what you are running and makes updates deliberate rather than whatever
main happened to publish. :edge is described as the unreleased build, which is
what it actually is.

The same stale claim appeared a second time in the Development section, saying
:latest is currently amd64-only. Both are corrected.

"How it works" described the app image as ghcr.io/calnode/calnode:latest. It is
actually the image named by the module's org.nethserver.images label, which is
the matching app release, so the module and app cannot drift apart. Saying
:latest there was wrong for every release since the label scheme landed.

Added a Data and privacy section. It says what is stored, that the encryption
key lives in the cluster state and is never transmitted, that nothing phones
home, and, honestly, that mail and backups both hand data to whatever provider
the operator configures. That last part is the one that matters: a reader
should not have to infer it. This is what metadata.json terms_url now points at.

metadata.json also had two dead links. code_url pointed at
github.com/calnode/ns8-calnode, which does not exist and returns 404: the
module lives in the monorepo, so it now points at calnode/calnode.
documentation_url pointed at the repository root rather than any documentation;
it now points at this README, which is the administrator documentation, and is
the first thing a reviewer or an installer would want. Both URLs verified 200.

No behaviour change. Nothing here is loaded at runtime except metadata.json,
which the Apps UI reads.
@pullfrog

pullfrog Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

The model provider returned an error, so this run stopped.

The error is below. If it names your key, plan or balance, fix that with the provider or pick another model before re-triggering.

Model settings → · Ask in Discord →

provider error: This API key has expired. Create a new API key in OpenCode Console and replace it in your client or secret store. Signing in again will not renew this key.

Pullfrog  | Rerun failed job ➔ | View workflow run | via Pullfrog | Using space-bunny-free (free) | 𝕏

@pullfrog

pullfrog Bot commented Oct 18, 2026

Copy link
Copy Markdown
Contributor

The model provider returned an error, so this run stopped.

The error is below. If it names your key, plan or balance, fix that with the provider or pick another model before re-triggering.

Model settings → · Ask in Discord →

provider error: This API key has expired. Create a new API key in OpenCode Console and replace it in your client or secret store. Signing in again will not renew this key.

Pullfrog  | Rerun failed job ➔ | View workflow run | via Pullfrog | Using space-bunny-free (free) | 𝕏

@shockalotti

Copy link
Copy Markdown
Contributor Author

Reviewing this properly rather than skimming it.

The content is right. I checked it against the shipped state: :latest, 0.11.1 and 0.11 are the same multi-arch release, so the old "do not use :latest" warning was genuinely outdated and this correctly replaces it with "pin a version, :latest is now safe". The org.nethserver.images wording matches how the module actually resolves the app image. The metadata.json fixes are correct too: code_url pointed at the module repo rather than the app repo, and documentation_url pointed at the repo root rather than the install guide.

Two things block it.

  1. The PR body is byte-identical to feat(ns8): make a cloned instance release its hostname #157, and it opens with "Follow-up to docs(ns8): correct the install guidance and declare data handling #156", which refers to this PR. The description is about the clone-module feature, which is feat(ns8): make a cloned instance release its hostname #157. Anyone reading this PR later would believe it shipped a feature it does not contain. Please rewrite the body to describe only what changed here: the install guidance correction, the multi-arch statement, and the metadata URLs.

  2. It collides with feat(ns8): make a cloned instance release its hostname #157. Both add a section at README line 129, so feat(ns8): make a cloned instance release its hostname #157 cannot merge after this without a conflict. That is fine, this is a stacked pair, but it needs to be stated: this one merges first, then feat(ns8): make a cloned instance release its hostname #157 rebases onto main.

Not requesting changes to the code. The docs are accurate. It is the description and the sequencing that need fixing.

@shockalotti
shockalotti merged commit e5caca5 into main Oct 21, 2026
10 of 13 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 21, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant