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

wtclaude · 2026-08-24T16:24:59Z

wtclaude commented

2026-08-24 16:24:59 +00:00

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

1. The shard screen moved and the guide did not

installer/INSTALL.md §5 and installer/PLAN.md both print the installer's handoff block, which told operators 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 four values have nowhere to go.

Both printed blocks now show the real path and the real label, Shard (uo-link).
The instruction under §5's block names the path explicitly, with a note for anyone whose earlier run printed the old one — installer v0.1.0 prints /admin/shard, and that is what is released today.
The note also records that API routes are unaffected by the module rule and keep /api/v1/admin/shard/*, because that is the distinction the next editor will need.

Matches installer#22, which fixes the binary and asserts the new path in both handoff tests.

2. 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 here from website#163, which fixes the file itself and was verified by booting the published image from a clean cp .env.example .env.

Checked but not changed

website/ARCHITECTURE.md already describes SECRET_ENC_KEY correctly (secrets at rest, and what a rotation means), and no document claimed the deployment works without it — the omission was only ever in the files an operator copies.

AI-assisted: written with Claude Code (Opus 5).

🤖 Generated with Claude Code

Two operator-facing errors, both found by following the documentation **exactly**, against a real deployment, while writing the runicgateway.com installation journey (runicgateway.com#10). ## 1. The shard screen moved and the guide did not `installer/INSTALL.md` §5 and `installer/PLAN.md` both print the installer's handoff block, which told operators 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 four values have nowhere to go. - Both printed blocks now show the real path and the real label, *Shard (uo-link)*. - The instruction under §5's block names the path explicitly, with a note for anyone whose earlier run printed the old one — **installer v0.1.0 prints `/admin/shard`**, and that is what is released today. - The note also records that **API routes are unaffected** by the module rule and keep `/api/v1/admin/shard/*`, because that is the distinction the next editor will need. Matches installer#22, which fixes the binary and asserts the new path in both handoff tests. ## 2. 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 here from website#163, which fixes the file itself and was verified by booting the published image from a clean `cp .env.example .env`. ## Checked but not changed `website/ARCHITECTURE.md` already describes `SECRET_ENC_KEY` correctly (secrets at rest, and what a rotation means), and no document claimed the deployment works without it — the omission was only ever in the files an operator copies. --- AI-assisted: written with Claude Code (Opus 5). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-08-24 16:25:00 +00:00

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

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>

whitlocktech merged commit 743fdbeb23 into main

2026-08-24 16:30:15 +00:00

whitlocktech deleted branch fix/admin-shard-path-and-secret-enc-key

2026-08-24 16:30:16 +00:00

whitlocktech referenced this issue from a commit

2026-08-24 16:30:17 +00:00

Merge pull request 'docs: the shard screen's real path, and the two keys a deploy cannot boot without' (#174) from fix/admin-shard-path-and-secret-enc-key into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#174