docs(selfhost): document the real update and rollback flow

[JSONbored]

Summary

• Adds an "Updating and rolling back" section to apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx (after the existing "Routine checks" section), grounded in the actual scripts/deploy-selfhost-image.sh and scripts/deploy-selfhost-prebuilt.sh (read both scripts in full before writing). Covers: what each script does and how it differs from a bare docker compose pull/up (restarts only the gittensory service via --no-deps, waits on docker inspect health status, persists the resolved image/version back to .env); how to pin an exact tag or digest; that both scripts leave .env, gittensory-config/, every data volume (including the app's own /data volume where Codex/Claude Code auth material lives), Grafana's grafana-data volume, and any docker-compose.override.yml untouched; that there is no dedicated rollback script today (rollback = re-running one of the two scripts pointed at an older tag/digest/checkout); the forward-only migration caveat (grounded in scripts/check-migrations.mjs, which has no down-migration concept) and what to check before rolling back across a schema boundary; and pre/post-update checks, including that neither /health nor /ready reports a version so the release id has to be confirmed via .env or docker inspect instead.
• Advances docs(selfhost): define safe update and rollback flow #1823.

Note on scope vs. #1823's acceptance criteria: while this PR was in flight, PR #3191 (for the sibling issue #1829) merged to main and independently fixed the same generic/inaccurate "Upgrade flow" and "Rollback" sections on docs.self-hosting-releases.tsx that I had also touched — so I dropped my redundant edits to that file during rebase and kept only the new Operations section, which is the actual scope of #1823. #1823 also asks for an "optional script or make target" for repeatability; I did not add one since the issue marks it optional and the two existing scripts already cover the repeatable path. Everything else in #1823's acceptance criteria (source-checkout path, image-tag path, what's preserved, restart-only-app-service vs. recreate-profile-service guidance, migration/rollback expectations, pre/post-update checks) is addressed here, so I'm calling this "Advances," not "Closes" — it's a real, substantial step, and I want a maintainer to confirm it's the last piece before actually closing the issue.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue (Advances docs(selfhost): define safe update and rollback flow #1823).

Validation

• git diff --check
• npm run actionlint — not run standalone; no workflow files touched
• npm run typecheck
• npm run test:coverage — not run; this PR only touches apps/gittensory-ui/**, which Codecov does not gate (docs-only change, no src/** lines changed)
• npm run test:workers — not run; no Worker/backend code touched
• npm run build:mcp / npm run test:mcp-pack — not run; no MCP package code touched
• npm run ui:openapi:check — not run; no API/schema changes
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate — not run standalone this pass; npm ci reported 0 vulnerabilities on install and no dependency changes are in this diff
• Read scripts/deploy-selfhost-image.sh, scripts/deploy-selfhost-prebuilt.sh, scripts/lib/selfhost-deploy-common.sh, and scripts/check-migrations.mjs in full to ground every claim in the new section against actual script behavior (not guessed). No bug found in either deploy script during this read — this PR is documentation-only.
• Rebased onto fresh origin/main immediately before pushing; resolved a real conflict in docs.self-hosting-releases.tsx against the concurrently-merged docs(selfhost): align release upgrade/rollback docs with deploy scripts #3191 by taking main's version and dropping my duplicate edits there.

If any required check was skipped, explain why:

• This is a docs-only change confined to apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx. No src/**, scripts/**, migrations/**, or workflow files changed, so the backend/coverage/MCP/OpenAPI/audit checks above don't apply to this diff. I ran the UI-specific checks that do apply (ui:lint, ui:typecheck, ui:build) and the root typecheck, all green.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed. All example values (image tags/digests) are the same public placeholders already used elsewhere in these docs.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• N/A — no auth, cookie, CORS, GitHub App, Cloudflare, or session changes.
• N/A — no API/OpenAPI/MCP behavior changes.
• N/A — no UI component/state changes; prose-only additions using existing DocsPage/CodeBlock/Callout/FeatureRow primitives, no new components or layout.
• UI Evidence — see below.
• Public docs updated (this PR is entirely a docs update); no changelog touched.

UI Evidence

Not applicable — this PR is prose-only content added to an existing docs page using the page's existing components (CodeBlock, Callout, headings, lists) with no new layout, component, or visual styling changes. I built the UI (npm run ui:build, green) and spot-checked the rendered page in a local dev server: the new "Updating and rolling back" h2 and its four h3 subsections ("Path 1: pull a published image", "Path 2: build from the current git checkout", "Rollback: no dedicated command today", "Before and after any update") render correctly, appear in the page's auto-generated "On this page" table of contents with correct scroll-spy highlighting, and the Callout warning renders with the expected left-border styling — confirmed via the accessibility tree and DOM/style inspection rather than a screenshot (a full-page screenshot was also captured showing the section in context, but isn't committed per the review-evidence policy).

Notes

• Also fixes the page's <head> meta description to mention updates/rollback (previously only listed readiness/metrics/logs/dashboards/jobs/queues/routine checks).

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	78cf57c	Commit Preview URL Branch Preview URL	Jul 04 2026, 07:34 PM

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 19:33:19 UTC}

1 file · 1 AI reviewer · 1 blocker · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Review summary
The PR adds a focused operations-doc section for self-host updates and rollback, with the right high-level shape: it distinguishes image-based and source-based deploys, calls out forward-only migrations, and gives concrete pre/post checks. I do not see a code-level defect in the changed route, and CI already validates that the new Callout import and JSX compile. The main remaining issues are wording precision in the operational docs, not merge-blocking behavior.

Nits — 6 non-blocking

• nit: apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:286 says the scripts only persist one `.env` key, but the later verification command includes `GITTENSORY_IMAGE`, `GITTENSORY_VERSION`, and `SENTRY_RELEASE`, so tighten that sentence to name the exact key or keys per script.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:285 says operators do not need to back up preserved state "just to run either script," but the same section later requires a backup for schema changes, so make the exception more visible in the opening paragraph to avoid readers stopping at the stronger reassurance.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:394 says `GITTENSORY_IMAGE` or `SENTRY_RELEASE` records the deployed release, while the command also asks for `GITTENSORY_VERSION`; include `GITTENSORY_VERSION` in the prose so the source-based path is not under-described.
• apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:286: Change the singular `.env` wording to something like `they only update the deploy identity keys they own: GITTENSORY_IMAGE for image deploys, and the source-build release/version keys for prebuilt deploys` or explain why only one key is actually mutated.
• apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:285: Move the schema-change backup caveat into the opening paragraph with `This preservation is not a substitute for a database backup before schema migrations.`
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Concerns raised — review before merging

• Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 60 registered-repo PR(s), 50 merged, 442 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 60 PR(s), 442 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 60 PR(s), 442 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• No action.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review