RunicGateway/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: the shard screen's real path, and the two keys a deploy cannot boot without

Browse Source 
Two operator-facing errors, both found by following the documentation exactly
against a real deployment while writing the runicgateway.com installation
journey.

**The shard screen moved and the guide did not.** INSTALL.md §5 and PLAN.md both
print the installer's handoff block, which said to paste the four values at
`<site>/admin/shard`. Those screens belong to the `uo` module now, and a module
owns one path segment wherever it appears (MODULE_SYSTEM.md §2.8), so the page
is `/admin/uo/link`. The old path does not 404 — the SPA sends the operator to
the dashboard, so the link looks like it worked and the values have nowhere to
go. The instruction under the block now names the path, and a note warns anyone
whose earlier run printed the old one. API routes are unaffected by the module
rule and keep `/api/v1/admin/shard/*`; the note says so, because that is the
distinction the next editor will need. Matches installer#22.

**The README snapshot's quickstart could not boot.** website's root
`.env.example` never listed SECRET_ENC_KEY, and the "set at least" list omitted
both it and BOT_INTERNAL_KEY — each of which the server refuses to start without
in production, BOT_INTERNAL_KEY even on a deployment running no bot. Synced from
website#163, which fixes the file itself and was verified by booting the
published image from a clean `cp .env.example .env`.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
claude
2026-08-24 11:24:41 -05:00
parent afb2fea50a
commit b525386047
3 changed files with 19 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
installer/INSTALL.md
View File

@@ -56,7 +56,7 @@ Only the sidecar is exposed, and only to your website.
| Administrator / root | It writes into system directories and registers a service. | | Administrator / root | It writes into system directories and registers a service. |
| Outbound HTTPS | To `gitea.whitlocktech.com`, to fetch the bundle and the two artifacts. Nothing inbound is needed, and no Gitea account or git client is required. | | Outbound HTTPS | To `gitea.whitlocktech.com`, to fetch the bundle and the two artifacts. Nothing inbound is needed, and no Gitea account or git client is required. |
| The sidecar on the **same host** as the shard | The shard connects to `127.0.0.1:7788`. Splitting them is not supported — the loopback socket *is* the trust boundary for inbound commands. | | The sidecar on the **same host** as the shard | The shard connects to `127.0.0.1:7788`. Splitting them is not supported — the loopback socket *is* the trust boundary for inbound commands. |
| Admin access to your Runic Gateway site | The last step is pasting four values into Admin → Shard. | | Admin access to your Runic Gateway site | The last step is pasting four values into Admin → Shard (uo-link). |
**Back up first.** The overlay overwrites `Scripts/Scripts.csproj` (a stock file), and the patch **Back up first.** The overlay overwrites `Scripts/Scripts.csproj` (a stock file), and the patch
tier edits stock sources. A copy of `Scripts/` and `Config/` before you start costs nothing. tier edits stock sources. A copy of `Scripts/` and `Config/` before you start costs nothing.
@@ -150,7 +150,7 @@ one file); `doctor`, `update` and `uninstall` are run from it later. Examples be
3. **The hostname your website should use to reach this machine** — used only to compose the two 3. **The hostname your website should use to reach this machine** — used only to compose the two
URLs it prints at the end. The sidecar's bind address is frequently `127.0.0.1` or `0.0.0.0`, URLs it prints at the end. The sidecar's bind address is frequently `127.0.0.1` or `0.0.0.0`,
neither of which is something to hand to a website. neither of which is something to hand to a website.
4. **Your site's URL** — used only to print a clickable link to its Admin → Shard page. The 4. **Your site's URL** — used only to print a clickable link to its Admin → Shard (uo-link) page. The
installer never contacts your website. installer never contacts your website.
### An illustrative run ### An illustrative run
@@ -413,8 +413,8 @@ One manual step remains — connect the website to this sidecar:
Protocol version 4 Protocol version 4
Auth token 4f9c… (also in /etc/runicgateway/sidecar.toml) Auth token 4f9c… (also in /etc/runicgateway/sidecar.toml)
Paste these into Admin → Shard on your Runic Gateway site: Paste these into Admin → Shard (uo-link) on your Runic Gateway site:
https://your-site.example/admin/shard https://your-site.example/admin/uo/link
The token is write-only once saved — the site will never show it back to you. The token is write-only once saved — the site will never show it back to you.
``` ```
@@ -422,7 +422,14 @@ The token is write-only once saved — the site will never show it back to you.
Every value there comes from asking the installed sidecar itself (`--print-config`), not from a Every value there comes from asking the installed sidecar itself (`--print-config`), not from a
log file or a guess, so it cannot drift from what the service actually runs. log file or a guess, so it cannot drift from what the service actually runs.
On your site, sign in as an administrator and open **Admin → Shard (uo-link)**: On your site, sign in as an administrator and open **Admin → Shard (uo-link)** — `/admin/uo/link`.
> **Installer v0.1.0 prints `/admin/shard`.** Those screens belong to the `uo` module
> now, and a module owns one path segment wherever it appears, so the page moved. The old path
> does not 404 — the site sends you to the dashboard, which looks like the link worked. If your
> run printed the old path, use the sidebar. (API routes are unaffected and keep
> `/api/v1/admin/shard/*`.)
| Field on the page | Paste | | Field on the page | Paste |
|---|---| |---|---|

4
installer/PLAN.md
View File

@@ -1068,8 +1068,8 @@ One manual step remains — connect the website to this sidecar:
Protocol version 3 Protocol version 3
Auth token 4f9c... (also in /etc/runicgateway/sidecar.toml) Auth token 4f9c... (also in /etc/runicgateway/sidecar.toml)
Paste these into Admin → Shard on your Runic Gateway site: Paste these into Admin → Shard (uo-link) on your Runic Gateway site:
https://<your-site>/admin/shard https://<your-site>/admin/uo/link
The token is write-only once saved — the site will never show it back to you. The token is write-only once saved — the site will never show it back to you.
``` ```

5
website/website-README.md
View File

@@ -216,7 +216,12 @@ cp .env.example .env
# Edit .env and set at least: # Edit .env and set at least:
# DB_PASSWORD, DB_ROOT_PASSWORD (any strong values) # DB_PASSWORD, DB_ROOT_PASSWORD (any strong values)
# JWT_SECRET (a long random string) # JWT_SECRET (a long random string)
# SECRET_ENC_KEY (a different long random string)
# BOT_INTERNAL_KEY (a third one, 16+ chars — even with no bot)
# ADMIN_USERNAME, ADMIN_PASSWORD (your first admin login) # ADMIN_USERNAME, ADMIN_PASSWORD (your first admin login)
#
# SECRET_ENC_KEY and BOT_INTERNAL_KEY are not optional in production: the app
# refuses to start without them, so the container crash-loops before it listens.
docker compose pull && docker compose up -d # IMAGE_TAG defaults to `latest` docker compose pull && docker compose up -d # IMAGE_TAG defaults to `latest`
# pin a specific build (reproducible deploy / rollback): # pin a specific build (reproducible deploy / rollback):