docs(journey): phase 7 — the installation path and administration
All checks were successful
PR checks / checks (pull_request) Successful in 9m25s
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:
118
src/content/docs/docs/administration/troubleshooting.mdx
Normal file
118
src/content/docs/docs/administration/troubleshooting.mdx
Normal 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.
|
||||
Reference in New Issue
Block a user