docs: handbook page for the update check (#793 docs pass) #794

Merged
Cordy merged 3 commits from docs-update-check-793 into main 2026-09-28 02:34:27 +00:00
Owner

Adds docs/handbook/updates.md and cross-links it from admin-policy.md (Updates), deployment.md (config anatomy) and the handbook index. Docs only; no code changes.

The page documents today's behaviour: off by default. It was verified against internal/api/updates.go, internal/config/config.go and the admin UI on main @ cc9ef3f. #793 flips the default, and this page lists what changes when it does.

Covered:

  • What the request carries: a plain GET with Accept, an optional token, and Go's default UA. Nothing about the instance. What the feed operator can observe.
  • When it runs: needs both check and tagsUrl; armed on the first admin view; refreshes every 24h plus the button; cached; 8s timeout; last known tag kept on failure.
  • The updates block, field by field. Notes that applyHint is accepted but not rendered yet (#793 point 7).
  • Version rules: strict vX.Y.Z, pre-releases ignored, a dev build never shows "update available". Pagination: one page only, so use per_page / limit.
  • Recipes: public feed, private mirror with token, egress proxy (HTTPS_PROXY), internal CA (SSL_CERT_FILE).
  • Air-gapped: leave it off, or run an internal "approved versions" feed (static tags.json) that becomes part of the image-import change process.
  • Verification steps and a troubleshooting table keyed on the exact error strings.

Refs #793, #180, #724, #727, #27.

🤖 Generated with Claude Code

https://claude.ai/code/session_01URkdo5CoTxpuNU5uvUSWzA

Adds `docs/handbook/updates.md` and cross-links it from `admin-policy.md` (Updates), `deployment.md` (config anatomy) and the handbook index. Docs only; no code changes. The page documents **today's behaviour: off by default**. It was verified against `internal/api/updates.go`, `internal/config/config.go` and the admin UI on main @ cc9ef3f. #793 flips the default, and this page lists what changes when it does. Covered: - **What the request carries:** a plain GET with `Accept`, an optional token, and Go's default UA. Nothing about the instance. What the feed operator can observe. - **When it runs:** needs both `check` and `tagsUrl`; armed on the first admin view; refreshes every 24h plus the button; cached; 8s timeout; last known tag kept on failure. - **The `updates` block, field by field.** Notes that `applyHint` is accepted but not rendered yet (#793 point 7). - **Version rules:** strict `vX.Y.Z`, pre-releases ignored, a dev build never shows "update available". **Pagination:** one page only, so use `per_page` / `limit`. - **Recipes:** public feed, private mirror with token, egress proxy (`HTTPS_PROXY`), internal CA (`SSL_CERT_FILE`). - **Air-gapped:** leave it off, or run an internal **"approved versions" feed** (static `tags.json`) that becomes part of the image-import change process. - **Verification** steps and a **troubleshooting** table keyed on the exact error strings. Refs #793, #180, #724, #727, #27. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01URkdo5CoTxpuNU5uvUSWzA
What the request carries (nothing about the instance), schedule and
caching, the updates config block field by field, version rules and
pagination, private mirrors, proxies and internal CAs, air-gapped
"approved versions" feeds, verification and troubleshooting. Documents
today's off-by-default behaviour; #793 flips it.
docs: link the update-check handbook page (#793)
All checks were successful
ci / test-and-build (pull_request) Successful in 1m32s
b0446ba80d
Cross-links docs/handbook/updates.md from admin-policy (Updates), deployment (config anatomy) and the handbook index. One-shot, self-removing.
Cordy scheduled this pull request to auto merge when all checks succeed 2026-09-28 02:32:55 +00:00
Cordy merged commit ce24181ead into main 2026-09-28 02:34:27 +00:00
Cordy deleted branch docs-update-check-793 2026-09-28 02:34:29 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
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#794
No description provided.