fix(docs): clear the quickstart drift the upstream fixes caused #11

Merged
whitlocktech merged 2 commits from fix/quickstart-drift-and-installer-note into main 2026-08-24 17:32:51 +00:00
4 changed files with 38 additions and 23 deletions

19
PLAN.md
View File

@@ -86,7 +86,7 @@ All values re-read from the Gitea API on **2026-08-19**, after revision 1.
| **Current bundle** | **2026.08.19** (protocol 4, generated 09:05:52Z) | `installer` branch `bundles``current.json` | | **Current bundle** | **2026.08.19** (protocol 4, generated 09:05:52Z) | `installer` branch `bundles``current.json` |
| uo-link sidecar | **v2.0.0** (2026-08-19) | release; in bundle 2026.08.19 | | uo-link sidecar | **v2.0.0** (2026-08-19) | release; in bundle 2026.08.19 |
| Plugin overlay | **v1.0.0** (2026-08-19) | release; in bundle 2026.08.19 | | Plugin overlay | **v1.0.0** (2026-08-19) | release; in bundle 2026.08.19 |
| Installer | **v0.1.0** (2026-08-07) | release | | Installer | **v0.1.1** (2026-08-24) | release |
| `module-uo` | **v1.0.1** (2026-08-19) | release | | `module-uo` | **v1.0.1** (2026-08-19) | release |
| Android app | **v0.5.0** (2026-08-08), id `com.runicgateway.app` | release; `app/build.gradle.kts` | | Android app | **v0.5.0** (2026-08-08), id `com.runicgateway.app` | release; `app/build.gradle.kts` |
| ServUO | **57.4** — min version, and the only version the patch tier is verified against | bundle `overlay.servuo` | | ServUO | **57.4** — min version, and the only version the patch tier is verified against | bundle `overlay.servuo` |
@@ -909,12 +909,21 @@ Hero editor into Branding and theming, Web Bot Activity into Authentication.
it is **missing from website's root `.env.example`**, the file Compose actually reads. It is it is **missing from website's root `.env.example`**, the file Compose actually reads. It is
present in `server/.env.example`, which is the file local development copies, which is why this present in `server/.env.example`, which is the file local development copies, which is why this
has never bitten anyone in dev. The quickstart carries it, declared as an upstream omission so the has never bitten anyone in dev. The quickstart carries it, declared as an upstream omission so the
check fails the day it is fixed. check fails the day it is fixed. **Fixed in website#163** (merged 2026-08-24), which also adds
`BOT_INTERNAL_KEY` to the README's "set at least" list — required in production even on a
deployment running no bot. The declaration did exactly what it was built to do: this repo went red
on the next run, and the entry is deleted here.
- **The installer points operators at a screen that no longer exists.** It prints - **The installer points operators at a screen that no longer exists.** It prints
`<site>/admin/shard`, and INSTALL.md §5 repeats it. Since the module-system cutover a module owns `<site>/admin/shard`, and INSTALL.md §5 repeats it. Since the module-system cutover a module owns
one path segment, and the screen is **`/admin/uo/link`**, labelled *Shard (uo-link)*. Both the one path segment, and the screen is **`/admin/uo/link`**, labelled *Shard (uo-link)*. The old path
binary (`installer` `main:src/sidecar.rs`) and the guide are stale; the journey documents the real does not even 404 — the SPA sends the operator to the dashboard, so the link looks like it worked
path and says the printed one does not resolve. and the four values have nowhere to go. **Fixed in installer#22** (the path is a named constant and
both handoff tests assert it) **and docs#174**, both merged 2026-08-24, and shipped in installer
**v0.1.1**. Getting there found a fourth defect, in `installer`'s release pipeline: the run for the
fix built every artifact and pushed tag `v0.1.1`, then took a `500` from `POST /releases` one
second later, leaving an orphan tag and no binaries. Re-running the workflow published it — the
failure was a race with the tag push, not a structural one — so the note here names v0.1.0 as the
version that prints the old path rather than describing the installer as currently wrong.
- **The admin "Restart the server" button opens a `window.confirm`.** Its text is the honest - **The admin "Restart the server" button opens a `window.confirm`.** Its text is the honest
warning that a deployment with no supervisor does not come back — which is exactly why warning that a deployment with no supervisor does not come back — which is exactly why
`restart: unless-stopped` is called out as load-bearing on the install page rather than left as `restart: unless-stopped` is called out as load-bearing on the install page rather than left as

View File

@@ -106,10 +106,17 @@ sidebar — `/admin/uo/link`. Tick *Enable the shard integration*, paste **Base
**WebSocket URL**, **Auth token** and **Protocol**, and save. The ingest client restarts **WebSocket URL**, **Auth token** and **Protocol**, and save. The ingest client restarts
immediately. immediately.
<Aside type="caution" title="The installer prints an older path for that screen"> <Aside type="caution" title="Installer v0.1.0 prints an older path for that screen">
It prints `…/admin/shard`. Since the shard screens became part of the `uo` module, a module v0.1.0 prints `…/admin/shard`. Since the shard screens became part of the `uo` module — and
owns one path segment and the screen moved to **`/admin/uo/link`**. Use the sidebar, or a module owns one path segment wherever it appears — the screen moved to
that path; the printed link no longer resolves. **`/admin/uo/link`**.
The old path does not fail visibly: the site has no route for it, so it sends you to the
dashboard, and that looks like the link worked. The four values you were just told to paste
then have nowhere to go. Use the sidebar, or the path above.
Fixed in **v0.1.1**, which prints the real path. Only matters if you are running the older
binary.
</Aside> </Aside>
The token is encrypted at rest and **never returned to any client** — losing it means The token is encrypted at rest and **never returned to any client** — losing it means

View File

@@ -27,7 +27,7 @@
"releases": { "releases": {
"link": "v2.0.0", "link": "v2.0.0",
"installer": "v0.1.0", "installer": "v0.1.1",
"Module-uo": "v1.0.1", "Module-uo": "v1.0.1",
"Android-app": "v0.5.0" "Android-app": "v0.5.0"
}, },

View File

@@ -110,22 +110,21 @@ export const env = [
]; ];
/** /**
* `SECRET_ENC_KEY` is in this quickstart and NOT in upstream's `.env.example`, which is why * Keys this quickstart sets that upstream's `.env.example` does not, each with the reason.
* it needs a declaration rather than passing quietly.
* *
* Found by booting this exact file against the published image (phase 7): the server calls * **Empty, and that is the point.** Its one entry was `SECRET_ENC_KEY`: phase 7 booted this
* `resolveKey()` in `utils/secretBox.js` at require time and throws * exact file against the published image and the container crash-looped before it ever
* `SECRET_ENC_KEY must be set in production`, so the container crash-loops before it ever * listened, because `resolveKey()` in `utils/secretBox.js` throws
* listens. It is documented in `server/.env.example` — the file local development copies — * `SECRET_ENC_KEY must be set in production` at require time. The variable was documented in
* and missing from the root `.env.example` that Compose actually reads. * `server/.env.example` — the file local development copies — and missing from the root
* `.env.example` that Compose actually reads.
* *
* The check treats the omission as upstream's bug, not as licence: it fails the moment the * The declaration was written so it could not outlive the defect: the check fails the moment
* variable appears in `.env.example`, so this note cannot outlive the defect it describes. * a declared key appears upstream. website#163 fixed `.env.example`, this repo went red on
* the next run, and the entry was deleted. Keep the export — the next divergence gets an
* entry here rather than passing quietly.
*/ */
export const notInUpstreamEnvExample = { export const notInUpstreamEnvExample = {};
SECRET_ENC_KEY:
"the app refuses to start in production without it (utils/secretBox.js), but website's root .env.example does not list it",
};
/** /**
* Variables upstream's `.env.example` carries that the quickstart leaves out, each with the * Variables upstream's `.env.example` carries that the quickstart leaves out, each with the