Update check: on by default against the public release feed (+ flip the docs) #793

Closed
opened 2026-09-28 02:28:55 +00:00 by Cordy · 0 comments
Owner

Why

The update check (#180) was meant to be on by default. Today it is off unless the operator configures it. swisscairn.ch already describes the on-by-default behaviour ("your instance checks for new versions once a day"). That is intentional, because this issue makes it true before launch.

Current state (main @ cc9ef3f)

  • internal/config/config.go UpdatesConfig: check (bool, omitempty) and tagsUrl both default empty/false. adminUpdates reports checkEnabled: false unless both are set (internal/api/updates.go ~L182).
  • When enabled, latestTag() sends a plain GET tagsUrl with Accept: application/json and an optional Authorization: token …. Go's default User-Agent is used. No version, instance name or user count is sent. The semver comparison happens locally.
  • The daily pollLoop is armed lazily by the first result() call, i.e. the first admin page view. It is not armed at boot.

Change

  1. Default on. With no updates block, check the public release feed: the GitHub mirror's tags endpoint, once #27 exists. An explicit "check": false must still switch it off. That requires telling unset apart from false: check is a plain bool with omitempty today, so move to *bool or add an explicit "disabled" field.
  2. Default releaseUrlTemplate pointing at the mirror's release page for {version}.
  3. Pagination. GitHub's /tags returns 30 entries per page, in an order that is not semver order. With the default URL, use ?per_page=100 or switch the default to a feed that cannot miss the newest tag. Add a test with more than 30 tags.
  4. Consider arming the poll loop at boot when the default is on, so "daily" is true even if no admin ever opens the admin UI. Decide and document.
  5. Air-gapped behaviour. With default on, an air-gapped instance would show "Update check failed: …" every day. Either make the failure state quiet and explanatory, or make the air-gapped docs say clearly: set "check": false, or point tagsUrl at an internal feed.
  6. Fix the admin UI's own claim. updSentV (web/static/index.html, 4 languages) says "A version string. No instance name, …", but nothing about the instance is sent. Align it with the code and with EULA.md §3 ("transmits nothing about your instance").
  7. applyHint is accepted in config and returned by /api/v1/admin/updates, but the UI never renders it. Wire it (gitops / compose / manual how-to text) or drop the field.

Docs flip (required for this issue to close)

The handbook currently documents off by default. When the default changes, update all of these:

  • docs/handbook/updates.md (added for this issue's docs pass): the "Default" section, the example that turns it on, and the air-gapped section (which becomes "how to switch it off or redirect it").
  • docs/handbook/admin-policy.md → "Updates" section.
  • docs/handbook/deployment.md → config anatomy bullet for updates.
  • EULA.md §3: "The optional update check, if you configure it, …" becomes on by default, with how to disable it.
  • swisscairn.ch (cairn-site): changelog.html and privacy wording must match the final behaviour, including the "sends a version string" sentence, which is wrong either way (see point 6).

Done when

  • A fresh instance with no updates block shows a real comparison under Administration → Updates.
  • "check": false shows "not configured / disabled".
  • An internal tagsUrl still works.
  • Tests cover the unset, false and true cases, plus pagination.
  • Every doc listed above says the same thing as the code.
## Why The update check (#180) was meant to be **on by default**. Today it is off unless the operator configures it. swisscairn.ch already describes the on-by-default behaviour ("your instance checks for new versions once a day"). That is intentional, because this issue makes it true before launch. ## Current state (main @ cc9ef3f) - `internal/config/config.go` `UpdatesConfig`: `check` (bool, omitempty) and `tagsUrl` both default empty/false. `adminUpdates` reports `checkEnabled: false` unless **both** are set (`internal/api/updates.go` ~L182). - When enabled, `latestTag()` sends a plain `GET tagsUrl` with `Accept: application/json` and an optional `Authorization: token …`. Go's default User-Agent is used. No version, instance name or user count is sent. The semver comparison happens locally. - The daily `pollLoop` is armed lazily by the first `result()` call, i.e. the first admin page view. It is not armed at boot. ## Change 1. **Default on.** With no `updates` block, check the public release feed: the GitHub mirror's tags endpoint, once #27 exists. An explicit `"check": false` must still switch it off. That requires telling unset apart from `false`: `check` is a plain `bool` with `omitempty` today, so move to `*bool` or add an explicit `"disabled"` field. 2. **Default `releaseUrlTemplate`** pointing at the mirror's release page for `{version}`. 3. **Pagination.** GitHub's `/tags` returns 30 entries per page, in an order that is not semver order. With the default URL, use `?per_page=100` or switch the default to a feed that cannot miss the newest tag. Add a test with more than 30 tags. 4. **Consider arming the poll loop at boot** when the default is on, so "daily" is true even if no admin ever opens the admin UI. Decide and document. 5. **Air-gapped behaviour.** With default on, an air-gapped instance would show "Update check failed: …" every day. Either make the failure state quiet and explanatory, or make the air-gapped docs say clearly: set `"check": false`, or point `tagsUrl` at an internal feed. 6. **Fix the admin UI's own claim.** `updSentV` (web/static/index.html, 4 languages) says "A version string. No instance name, …", but nothing about the instance is sent. Align it with the code and with `EULA.md` §3 ("transmits nothing about your instance"). 7. **`applyHint`** is accepted in config and returned by `/api/v1/admin/updates`, but the UI never renders it. Wire it (gitops / compose / manual how-to text) or drop the field. ## Docs flip (required for this issue to close) The handbook currently documents **off by default**. When the default changes, update all of these: - `docs/handbook/updates.md` (added for this issue's docs pass): the "Default" section, the example that turns it on, and the air-gapped section (which becomes "how to switch it off or redirect it"). - `docs/handbook/admin-policy.md` → "Updates" section. - `docs/handbook/deployment.md` → config anatomy bullet for `updates`. - `EULA.md` §3: "The optional update check, if you configure it, …" becomes on by default, with how to disable it. - swisscairn.ch (cairn-site): changelog.html and privacy wording must match the final behaviour, including the "sends a version string" sentence, which is wrong either way (see point 6). ## Done when - A fresh instance with no `updates` block shows a real comparison under Administration → Updates. - `"check": false` shows "not configured / disabled". - An internal `tagsUrl` still works. - Tests cover the unset, false and true cases, plus pagination. - Every doc listed above says the same thing as the code.
Cordy closed this issue 2026-10-01 13:48:42 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#793
No description provided.