From 81ce5ab8811c9c2bacf7b68c768f0ee770b1fe58 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Sat, 4 Jul 2026 12:24:27 -0700
Subject: [PATCH] docs(selfhost): align release upgrade/rollback docs with
 deploy scripts (#1829)

The Upgrade flow and Rollback sections on the self-host releases doc described a
generic docker compose pull/up cycle instead of the two deploy scripts the repo
actually ships (deploy-selfhost-image.sh, deploy-selfhost-prebuilt.sh), which add
input validation and a health-check wait loop a bare compose invocation skips.
Rollback also didn't mention that migrations are forward-only, so reverting the
app image after a migration has already run leaves the schema ahead of the code.
---
 .../src/routes/docs.self-hosting-releases.tsx | 43 +++++++++++++++----
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx
index fa667cbbba..c76a89df1a 100644
--- a/apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx
+++ b/apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx
@@ -82,18 +82,35 @@ docker pull ghcr.io/jsonbored/gittensory-selfhost:latest`}
       <ol>
         <li>Read release notes for env, migration, or behavior changes.</li>
         <li>Back up the database or confirm Litestream health.</li>
-        <li>Pull the new image tag.</li>
-        <li>Recreate the app container.</li>
+        <li>
+          Pull and restart with <code>scripts/deploy-selfhost-image.sh</code> (or rebuild the
+          checkout with <code>scripts/deploy-selfhost-prebuilt.sh</code>) — both restart only the{" "}
+          <code>gittensory</code> service (<code>--no-deps</code>) and wait for it to report{" "}
+          <code>healthy</code> before returning, instead of a bare <code>docker compose up -d</code>{" "}
+          that returns as soon as the container starts.
+        </li>
         <li>
           Check <code>/ready</code>, logs, queue metrics, and one test PR.
         </li>
       </ol>
       <CodeBlock
         lang="bash"
-        code={`docker compose pull gittensory
-docker compose up -d gittensory
-curl http://localhost:8787/ready`}
+        code={`# Recommended: pull a published tag, restart, wait for healthy
+./scripts/deploy-selfhost-image.sh ghcr.io/jsonbored/gittensory-selfhost:orb-v0.1.0
+curl http://localhost:8787/ready
+
+# Building from the current checkout instead of pulling
+./scripts/deploy-selfhost-prebuilt.sh`}
       />
+      <Callout variant="note">
+        Both scripts pin a version: the image script accepts a tag/digest argument or{" "}
+        <code>GITTENSORY_IMAGE</code>; the prebuilt script derives <code>SENTRY_RELEASE</code>/
+        <code>GITTENSORY_VERSION</code> from the checked-out commit (
+        <code>git rev-parse --short=8 HEAD</code>) unless you set <code>SENTRY_RELEASE</code>{" "}
+        yourself. A plain{" "}
+        <code>docker compose pull gittensory &amp;&amp; docker compose up -d gittensory</code> still
+        works, but skips the health-check wait loop and input validation both scripts provide.
+      </Callout>
 
       <h2>Custom images</h2>
       <p>
@@ -118,10 +135,20 @@ docker compose up -d gittensory`}
 
       <h2>Rollback</h2>
       <p>
-        Roll back by pinning the prior image tag and recreating the container. Database migrations
-        can make rollback harder, so keep backups and read release notes before upgrading a live
-        maintainer instance.
+        There is no dedicated rollback command. Roll back by re-running{" "}
+        <code>scripts/deploy-selfhost-image.sh</code> pinned to the prior image tag or digest (or{" "}
+        <code>scripts/deploy-selfhost-prebuilt.sh</code> against an older checkout) — the same
+        script you upgrade with, pointed backward.
       </p>
+      <Callout variant="warn" title="Migrations are forward-only">
+        This repo has no down-migration convention (<code>scripts/check-migrations.mjs</code> and{" "}
+        <code>migrations/</code> only ever add forward). If a migration already ran forward before
+        you need to roll back, reverting the app image does not revert the schema — the rolled-back
+        code now runs against a newer schema than it expects. Keep backups and read release notes
+        for migration changes before upgrading a live maintainer instance, and treat a
+        post-migration rollback as a case that needs a manual schema/data plan, not just an image
+        swap.
+      </Callout>
     </DocsPage>
   );
 }