docs(deploy): correct stale infra facts after GCP name-alignment

The deploy docs predated the GCP name-alignment and described
infrastructure that no longer exists. Discovered during the v0.31.4
deploy. Corrections:

- Project wiggleverse-rfc -> wiggleverse-ohm; VM rfc-app -> ohm-rfc-app;
  install path /opt/rfc-app -> /opt/ohm-rfc-app; system user + service
  rfc-app -> ohm-rfc-app; external IP 34.132.29.41 -> 136.116.40.66.
- SSH is now IAP-only (direct port 22 times out): document
  --tunnel-through-iap on every gcloud compute ssh.
- Meta repo wiggleverse/meta -> wiggleverse/ohm-content.
- Two-remote reality: the VM's git origin is git.benstull.org/benstull/
  rfc-app, a SEPARATE Gitea from the release one (git.wiggleverse.org)
  that does not auto-mirror — so a release must be pushed to the
  benstull remote before the VM can fetch it. The VM tracks a detached
  release TAG, not a branch.
- Frontend-only changes are live once dist/ is rebuilt (nginx serves it
  directly); pip install only when requirements.txt changed.

Docs-only; no version bump (cf. the docs-only commit after v0.31.3).
The First-Time Deployment blocks keep the structural commands with a
substitution note rather than unvalidated rewrites.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Ben Stull
2026-06-01 10:15:58 -07:00
parent 551d240967
commit 714c2aed86
2 changed files with 124 additions and 40 deletions
+45 -10
View File
@@ -1,9 +1,26 @@
# Runbook
Single-host deployment of the RFC app at `ohm.wiggleverse.org`, sharing
infrastructure with `git.wiggleverse.org` (same Gitea instance, same nginx,
same Let's Encrypt). The shape matches §4.2: one process, one SQLite file,
no separate worker.
Single-host deployment of the RFC app at `ohm.wiggleverse.org`. The shape
matches §4.2: one process, one SQLite file, no separate worker.
> **⚠️ Current deployment names (post GCP name-alignment, ~2026-05).**
> The command blocks below were written with the original names and use
> `/opt/rfc-app`, system user `rfc-app`, and service `rfc-app`. The live
> OHM box uses the realigned names — substitute throughout:
>
> | Was | Now |
> | --- | --- |
> | GCP project `wiggleverse-rfc` | `wiggleverse-ohm` |
> | VM `rfc-app` | `ohm-rfc-app` |
> | install path `/opt/rfc-app` | `/opt/ohm-rfc-app` |
> | system user `rfc-app` | `ohm-rfc-app` |
> | service `rfc-app.service` | `ohm-rfc-app.service` |
> | SSH | IAP-only: `gcloud compute ssh ohm-rfc-app --zone=us-central1-a --project=wiggleverse-ohm --tunnel-through-iap` |
> | meta repo `wiggleverse/meta` | `wiggleverse/ohm-content` |
>
> The VM's git origin is **`git.benstull.org/benstull/rfc-app`** — a
> *different* Gitea from the release one (`git.wiggleverse.org`). See §2.5.
> The full current infra table lives in `DEPLOY-NEW-SESSION-PROMPT.md`.
Bring-up order: host prep → Gitea side (bot, OAuth, meta repo) → app side
(code, venv, build, .env) → web server side (nginx, certbot) → systemd →
@@ -345,16 +362,34 @@ pinned = 1 WHERE rfc_slug = ? AND branch_name = ?`).
### 2.5 Updating after a push
The live OHM box uses the realigned names (see the callout at the top)
and deploys by checking out a **release tag** (detached HEAD), not by
pulling a branch. Its git origin is `git.benstull.org/benstull/rfc-app`,
which does **not** auto-mirror from the release Gitea
(`git.wiggleverse.org`) — so first push `main` + the new tag there:
```sh
sudo -u rfc-app git -C /opt/rfc-app pull
sudo -u rfc-app /opt/rfc-app/backend/.venv/bin/pip install \
-r /opt/rfc-app/backend/requirements.txt
# Rebuild the frontend locally and rsync dist/ as in 1.3.2.
sudo systemctl restart rfc-app
# from your local rfc-app clone, on main at the merged release tip:
git push benstull main vX.Y.Z # benstull = git@git.benstull.org:benstull/rfc-app.git
```
Then on the VM (SSH is IAP-only):
```sh
gcloud compute ssh ohm-rfc-app --zone=us-central1-a --project=wiggleverse-ohm --tunnel-through-iap
sudo -u ohm-rfc-app git -C /opt/ohm-rfc-app fetch origin --tags
sudo -u ohm-rfc-app git -C /opt/ohm-rfc-app checkout vX.Y.Z
# only when backend deps changed:
sudo -u ohm-rfc-app /opt/ohm-rfc-app/backend/.venv/bin/pip install \
-r /opt/ohm-rfc-app/backend/requirements.txt
# frontend changes: build on the VM (Node 20+ is there) — output is served directly by nginx:
cd /opt/ohm-rfc-app/frontend && sudo -u ohm-rfc-app npm ci && sudo -u ohm-rfc-app npm run build
sudo systemctl restart ohm-rfc-app
```
The §5 schema migrations run on startup and are append-only. A restart
is the entire deploy.
is the entire backend deploy; a frontend-only change is live as soon as
the new `dist/` is built (nginx serves it directly).
---