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

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

Browse Source 
Reviewed-on: #174
This commit is contained in:
Colby Whitlock
2026-08-24 16:30:13 +00:00
parent afb2fea50a b525386047
commit 743fdbeb23
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):