docs(selfhost): align release upgrade/rollback docs with deploy scripts

[JSONbored]

Summary

• Advances docs(selfhost): audit website docs against runtime defaults #1829 (docs(selfhost): audit website docs against runtime defaults). This is a scoped,
  honest slice of that issue, not the full audit — see "What remains" below.
• Systematically diffed every apps/gittensory-ui/src/routes/docs.self-hosting-*.tsx page (excluding
  docs.self-hosting-rees-analyzers.tsx, tracked separately per the issue) against
  docker-compose.yml, .env.example, .env.selfhost.example, Dockerfile,
  .github/workflows/release-selfhost.yml, .github/workflows/selfhost.yml,
  scripts/deploy-selfhost-image.sh, and scripts/deploy-selfhost-prebuilt.sh. For every env var,
  confirmed its stated default/behavior against .env.example's actual default and the exact
  process.env.NAME read site in src/. For every compose service/profile mentioned, confirmed it
  still exists with the same name/behavior. For every release/deploy claim, confirmed it matches the
  actual workflow steps and the two deploy scripts.
• Result: 11 of 12 in-scope pages were already accurate against current runtime defaults (this repo
  already has scripts/check-docs-drift.mjs from docs(gittensory-ui): fix stale website docs and add a CI docs-drift check #3059/feat(ci): add a docs-drift check for GITTENSORY_REVIEW_* flags, @gittensory commands, and gate-mode dimensions #3047 catching flag/command/gate-field drift,
  and it's working). One confirmed, real gap found and fixed in docs.self-hosting-releases.tsx.

Docs accuracy checklist (drift found and fixed)

#	Location	Before	After
1	docs.self-hosting-releases.tsx — "Upgrade flow"	Told operators to run raw docker compose pull gittensory && docker compose up -d gittensory, which returns as soon as the container starts	Points at the actual scripts/deploy-selfhost-image.sh (pull + --no-deps restart + health-check wait loop + input validation) and scripts/deploy-selfhost-prebuilt.sh (build-from-checkout equivalent), matching what docs.self-hosting-quickstart.tsx already recommends for first boot; kept the raw compose command as a documented-but-inferior fallback
2	docs.self-hosting-releases.tsx — "Rollback"	"Roll back by pinning the prior image tag and recreating the container. Database migrations can make rollback harder..." — vague, and didn't name a mechanism	States plainly there is no dedicated rollback script/command (confirmed: neither deploy script nor any other script in scripts/ implements one) and that rollback today means re-running deploy-selfhost-image.sh/deploy-selfhost-prebuilt.sh pointed at an older tag/checkout; added an explicit callout that migrations are forward-only (confirmed: no down-migration convention in scripts/check-migrations.mjs or migrations/), so a rollback after a forward migration leaves the schema ahead of the reverted code — a real, previously-undocumented risk

What remains for #1829

This PR only had one confirmed drift to fix — the other 11 self-hosting doc pages
(ai-providers, backup-scaling, configuration, github-app, operations, quickstart, rag,
release-checklist, security, troubleshooting, maintainer-self-hosting) checked out accurate
against current docker-compose.yml profiles/services, .env.example defaults, and the generated
SELFHOST_ENV_REFERENCE_MARKDOWN table (regenerated locally via node scripts/gen-selfhost-env-reference.mjs; zero diff, so it's not stale either). I did not find
additional drift to fix in this pass. If the issue intends a broader net (e.g. extending
check-docs-drift.mjs's automated coverage to catch this class of prose-vs-script drift going
forward, not just flag/command/gate-field drift), that is out of scope for this PR and would be a
good separate follow-up.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused: one docs page, two related sections (upgrade + rollback), no unrelated changes.
• Follows CONTRIBUTING.md; no site//CNAME/VitePress/Pages changes.
• Advances docs(selfhost): audit website docs against runtime defaults #1829 (not a full close — see "What remains" above for why no closing keyword is used).

Validation

• git diff --check
• npm run actionlint (N/A — no workflow files changed)
• npm run typecheck — passes (ran via npm run ui:typecheck, the tsc project that covers this file; also confirmed the root install is current via npm ci)
• npm run test:coverage (N/A — no src/** lines changed; docs-only change under apps/gittensory-ui/**, which is not Codecov-scored)
• npm run test:workers (N/A — no worker code changed)
• npm run build:mcp (N/A — no MCP code changed)
• npm run test:mcp-pack (N/A — no MCP code changed)
• npm run ui:openapi:check (N/A — no API/schema changes)
• npm run ui:lint — 0 errors (87 pre-existing react-refresh/only-export-components warnings unrelated to this file, same baseline as main)
• npm run ui:typecheck — passes
• npm run ui:build — succeeds
• npm run docs:drift-check — passes (15 feature flags, 19 commands, 11 gate-mode fields all documented; this page isn't covered by that script's specific extractors, but ran it as a sanity check since it's the repo's docs-drift regression guard)
• npm audit --audit-level=moderate (not re-run standalone; npm ci during this session reported "found 0 vulnerabilities")
• New or changed behavior has unit/integration tests (N/A — prose-only change, no new code branches)

If any required check was skipped, explain why:

• This is a docs-only change (prose in one .tsx route file), so the backend-oriented checks
  (coverage/workers/mcp/openapi/actionlint) don't apply — matches the precedent in prior docs-only
  PRs on this repo (e.g. docs(selfhost): clarify checkRunMode duplicates the required gate check #2742, docs(gittensory-ui): fix stale website docs and add a CI docs-drift check #3059).

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 in the diff are pre-existing placeholders already in the file (ghcr.io/jsonbored/gittensory-selfhost:orb-v0.1.0, etc.) or references to script/file paths — no new example secrets were introduced.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no such change)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no API/OpenAPI/MCP change)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — no data-fetching UI change, static docs prose only)
• Visible UI changes include a UI Evidence section... (N/A — no visual/layout/component change, text-only edit to existing prose sections; see UI Evidence section below)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs (CHANGELOG.md untouched, per house rule).

UI Evidence

Not applicable — this changes prose text inside two existing <h2> sections (Upgrade flow,
Rollback) on an existing docs page. No layout, component, or visual change. Confirmed via
npm run ui:build that the route still builds; the rendered page structure (headings, callouts,
code blocks) is unchanged, only the text and one new Callout block inside the existing content
flow.

Notes

• Live-system ground truth used to verify the rollback finding (from a separate read-only
  session against the production self-host deployment, not re-derived here): the live deployment
  runs deploy-selfhost-prebuilt.sh from a git checkout, and there is genuinely no rollback script
  in the repo today — this PR documents that gap honestly rather than implying a rollback command
  exists.

[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	81ce5ab	Commit Preview URL Branch Preview URL	Jul 04 2026, 07:26 PM

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

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

1 file · 1 AI reviewer · 1 blocker · readiness 93/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
This is a scoped docs-only correction that replaces the weaker raw compose upgrade guidance with the deploy scripts already recommended by the quickstart, and it adds the important rollback caveat that migrations are forward-only. The visible changes are coherent with the PR description and do not introduce a runtime or build risk in the provided file. The main remaining issues are wording precision and keeping the release page aligned with the quickstart's health-check examples.

Nits — 5 non-blocking

• nit: apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx:97 The upgrade example checks only `/ready`, while the quickstart shows both `/health` and `/ready`; add `curl http:​//localhost:8787/health` before `/ready` so the release flow matches the existing operational path.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx:111 The sentence "Both scripts pin a version" is a little imprecise for `deploy-selfhost-prebuilt.sh`, which derives version metadata from the checked-out commit rather than pinning an external artifact; change it to "Both scripts record a concrete version" or split the image/prebuilt behavior explicitly.
• apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx:97 Mirror the quickstart snippet by showing both health probes after deploy: `curl http:​//localhost:8787/health` followed by `curl http:​//localhost:8787/ready`.
• apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx:111 Rephrase the note to distinguish artifact pinning from commit-derived provenance so operators do not read the prebuilt path as equivalent to a registry tag/digest pin.
• 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	⚠️ Missing	No linked issue or no-issue rationale found.
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.
• Explain no-issue PR.
• 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