docs(journey): phase 7 — the installation path and administration
All checks were successful
PR checks / checks (pull_request) Successful in 9m25s

Twenty documentation pages: Getting started (7) and Administration (13), the
journey no existing document owns end to end because the repositories are
organised by component and an operator is not.

Four decisions of record, taken before anything was written (D34–D37, PLAN.md
§10 "How phase 7 built the documentation journey"):

- D34 one PR for all twenty pages.
- D35 the install page is SELF-CONTAINED: it prints a complete Compose file and
  a complete .env that an operator copies without visiting another repository.
  That is a copy of somebody else's file, so it is checked rather than trusted —
  scripts/checkQuickstart.mjs re-reads website main:docker-compose.yml and
  main:.env.example over the Gitea API and fails on any disagreement, in both
  directions: a value that drifts fails, and a service or variable that appears
  upstream fails until it is either included or recorded as deliberately omitted
  with a reason. Its first run found two stale entries.
- D36 every Administration screen was walked on a real deployment before it was
  described — the rig being the quickstart itself, against the published image,
  so one run proved the install page and produced the detail the admin pages
  needed.
- D37 a thirteenth Administration page, Content, so that every admin nav row has
  a home without organising the docs by the app's menu.

What the live deployment disproved, all three now documented:

- The documented Compose deploy does not boot. SECRET_ENC_KEY is required in
  production (utils/secretBox.js throws at require time) and is missing from
  website's ROOT .env.example — the file Compose reads. It is present in
  server/.env.example, which is why dev never hits it. The quickstart carries it,
  declared as an upstream omission so the check fails the day it is fixed.
- The installer points operators at a screen that no longer exists: it prints
  <site>/admin/shard, and INSTALL.md §5 repeats it, but since the module cutover
  the screen is /admin/uo/link. Both the binary and the guide are stale.
- The admin Restart button opens a window.confirm whose text is the honest
  warning that a deployment with no supervisor does not come back — which is why
  `restart: unless-stopped` is called out as load-bearing rather than left as
  boilerplate.

And the defect only a look found, three phases running: the .env block's prose
promised that every highlighted line must be changed, while `mark` given the
variable names highlighted the names alone and left the values unmarked. Every
check passed on a page that was wrong about its own highlighting.

verify green: 890 internal links, 52 branch links, 19 facts, 59 quickstart
checks, 0 astro-check errors.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-24 08:35:03 -05:00
parent 971fa9c032
commit f499f2b72b
27 changed files with 2260 additions and 19 deletions

View File

@@ -0,0 +1,118 @@
---
title: Troubleshooting
description: The failures a deployment actually hits, what each one looks like, and the fix.
---
import { Aside } from '@astrojs/starlight/components';
Grouped by where the problem is, because the first useful question is always *which half is
broken*.
## The site will not start
Read the log first — `docker compose logs app` — because the server says exactly why.
| What the log says | What it means |
|---|---|
| `SECRET_ENC_KEY must be set in production` | The key that encrypts stored secrets is missing. Set it in `.env` and start again. The container crash-loops until you do. |
| A `BOT_INTERNAL_KEY` complaint | Blank, still a placeholder, or shorter than 16 characters. Required in production even when the bot is not running. |
| A database connection error, repeatedly | The app came up before the database was ready, or `DB_*` is wrong. The Compose file's health check handles the first case; check the values for the second. |
| Nothing at all, container restarting | The image did not pull. `docker compose pull` on its own shows the error. |
<Aside type="caution" title="Both of those key errors happen on the FIRST boot, not later">
They are checked at require time, before the server listens. A deployment that has ever
served a request has both of them set.
</Aside>
## Nobody can sign in
- **Your address is rate-limited or bot-banned.** Both are working as designed. Check
**Admin → Web Bot Activity** from another network, or restart the app container — the
scoring state is in memory and resets with it.
- **The password is right and the form still fails.** Check the log for the actual status:
a `429` is the rate limiter, a `403` is usually the honeypot, and a `401` really is the
password.
- **SSO returns to the login page.** SSO is link-only: an identity that is not already
linked to an account cannot sign in, and that is the expected outcome rather than a
misconfiguration. Link it from the account screen first.
- **Two-factor is lost.** Recovery codes, or another admin's **Reset two-factor** on
**Users → View**. See [Authentication](/docs/administration/authentication/).
## A module will not start
**Admin → Modules** names the stage and the reason. The usual three:
| Reason | Fix |
|---|---|
| `module directory not present on the volume` | The row exists and the files do not — someone deleted the directory by hand. Reinstall, or remove the row with an uninstall. |
| A schema failure | The module's schema fragment could not be applied. The log carries the SQL error. |
| A version refusal | The module wants a newer core API than this image. Upgrade the site. |
Whatever the reason, **the site is up and the module's routes are absent** — that is by
design, and it is why a broken module is an inconvenience rather than an outage. Fix the
cause and restart: failed modules are retried on every boot.
**The install button rejects a URL.** The host must be in the allowlist on the same screen,
and the URL must be HTTPS. An empty allowlist forbids every install.
**The install succeeds and nothing appears.** It needs a restart. The banner says so, and
the row reads *Restart to start* until then.
## The Restart button did not bring the site back
The button exits the process and relies on a supervisor to start it again. If your
deployment has nothing supervising it — `npm start` in a terminal, a container without
`restart:` — the site stays down until you start it yourself. Compose with
`restart: unless-stopped` is the supported shape.
## The game screens are empty or say offline
Work outwards from the game, and stop at the first check that fails.
1. **In game:** `[bridge status` — `connected=False` means the shard cannot reach the
sidecar.
2. **On the shard host:** `curl -s http://127.0.0.1:8080/health` — `plugin_connected: true`
is the value that matters.
3. **On the shard host:** `runicgateway doctor` — checks the install record, every overlay
file hash, the service, and that the sidecar and overlay agree on a protocol.
4. **On the site:** the [shard connection screen](/docs/administration/the-shard-connection/)
— its four indicators say which link is broken.
Two log lines with specific meanings: **`409`** is a protocol mismatch (set the Protocol
field to what `/health` reports), and **`401`** is the auth token (read the live one back
with `uo-link-sidecar --print-config`; do not retype it from a screenshot).
<Aside type="note" title="“Nothing changed and it stopped working” usually means a ServUO update">
An update to the server tree can revert `Scripts.csproj`, at which point the plugin sits in
the tree and never compiles — and ServUO ignores the script build's exit code, so the boot
looks clean. `doctor` catches it by comparing file hashes against the install record.
</Aside>
## Teams are missing
Check the sync panel on **Admin → Teams** before anything else: *last success: never* with
`no uo-link configured` means the shard connection, not the Team machinery. And on a site
with **no module installed**, an empty Team list is correct and final — core cannot create
a Team. See [Teams](/docs/administration/teams/).
## Email and announcements never arrive
- **The contact form opens a mail client.** Email delivery is not connected; that is the
documented fallback. Connect Gmail in **Settings → Email delivery** — after configuring
the Google provider, which it reuses.
- **A published post announced nothing.** The Discord bot is a separate container. If the
Discord Bot screen says *bot unreachable*, it is not running.
- **A missed announcement does not come back.** Nothing retries; the post itself is still
on the site.
## Uploads and modules fail with permission errors
Docker created a bind-mount source that the container user cannot write — usually because
the directory was deleted and recreated by Docker as `root`. `chown 1000:1000 modules` (or
`logs`, or `brand`) on the host fixes it. Do not delete those directories.
## When you need to ask for help
Bring three things: the relevant lines from `docker compose logs app`, the output of
`runicgateway doctor` if a game server is involved, and what you changed last. The
[community page](/community/) has where to ask.