From f98005eec0a6c25f21005a28c10bda8eb83d87b9 Mon Sep 17 00:00:00 2001 From: wtclaude Date: Fri, 7 Aug 2026 16:38:35 -0500 Subject: [PATCH] docs: bring the org profile up to current state Last touched 2026-07-23, before the installer repo existed. - Six repos, not five: add installer to the table. - Quick start: steps 2 (cargo build the sidecar) and 3 (see the plugin repo for deploy steps) collapse into one installer run, which is how a shard is actually set up now. The by-hand path is kept as a note. - Day-two commands and the note that the installer does not install itself, so nobody looks for `runicgateway` on PATH. - Mention what shipped since: the player-vendor marketplace, the spawn atlas, the admin-configurable shard visibility framework, and the account-security layer (TOTP + trusted devices, link-only SSO, bot scoring). - "Where to go next" leads with INSTALL.md; the link and servuo-plugins entry is now about working on them rather than deploying them. Verified rather than assumed: JDK 17 and min SDK 29 still match app/build.gradle.kts, and Node 20+ still matches the website README and its Dockerfile. Co-Authored-By: Claude --- README.md | 84 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 57 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ebad0d1..8271e56 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,13 @@ Runic Gateway is a self-hostable platform that gives a UO shard a public site, wiki, and admin panel — and wires it to the *live in-game world* so the site can show shard -status, economy, IDOCs, player activity, and per-character sheets, and staff can push -control commands back into the game. Players get the same public content and self-service -on the web **or** a native Android app. Branding is instance-configurable. +status, economy, IDOCs, player activity, per-character sheets, a player-vendor marketplace, +and a bestiary built from the shard's own spawn tables, while staff push control commands +back into the game. Players get the same public content and self-service on the web **or** +a native Android app. Which audience sees which shard data is admin-configurable, and +branding is per-instance. + +One installer sets up the shard side. @@ -16,13 +20,14 @@ on the web **or** a native Android app. Branding is instance-configurable. ## The pieces -Runic Gateway is five repositories that deploy together but build independently: +Runic Gateway is six repositories that deploy together but build independently: | Repo | Language | What it is | |------|----------|------------| | [**website**](https://gitea.whitlocktech.com/RunicGateway/website) | JavaScript (Node + React) | The full-stack app — Express REST API + MariaDB + a React/Vite SPA (public site, wiki, admin panel). This is the thing players and staff actually visit, and the single backend every client talks to. | | [**link**](https://gitea.whitlocktech.com/RunicGateway/link) | Rust | The **uo-link** sidecar. Runs next to the shard, terminates a loopback link from the game, and exposes the authenticated WebSocket + REST API the website consumes. The only network-facing half of the bridge. | | [**servuo-plugins**](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) | C# | The **ServUO plugin** — the shard side of the bridge. Compiled by ServUO at boot; dials the sidecar over loopback and emits game events / accepts commands. | +| [**installer**](https://gitea.whitlocktech.com/RunicGateway/installer) | Rust | The **installer** — one binary per OS that deploys the plugin and the sidecar onto a shard host as a matched, protocol-checked pair, registers the service, and hands you the values the website needs. How you set a shard up. | | [**Android-app**](https://gitea.whitlocktech.com/RunicGateway/Android-app) | Kotlin (Jetpack Compose) | The **native Android client** — public content + player self-service, purely an API client of the website backend. Same features as the browser client *minus* every admin console. Never touches the sidecar or shard. | | [**docs**](https://gitea.whitlocktech.com/RunicGateway/docs) | Markdown | All project documentation — design docs, the wire-protocol spec, the integration guide, the Android plan, research. Start here when you want the *why*. | @@ -47,19 +52,26 @@ ServUO shard ──loopback TCP,──▶ uo-link sidecar ──WS + REST─ - Players **link** a game account to a website account with a one-time in-game code, which is what authorizes character reads. Staff can push town-crier messages and control commands back into the game. +- **Accounts are hardened out of the box** — TOTP two-factor with trusted devices, optional + SSO (Google / Discord / any OIDC provider, link-only: an external identity must already + belong to an account), bot scoring with automatic IP bans, and rate limiting. +- **Who sees which shard data is configurable**, not hardcoded: an admin panel decides the + audience for each shard surface, and the public SSE channel can never carry a sensitive + event kind. The connection between website and sidecar (URL, shared-secret token, protocol version) is -**admin-managed in the database**, not env — set once in the site's **Admin → Shard** panel. -If the sidecar is absent or the shard is down, every shard surface degrades gracefully. +**admin-managed in the database**, not env — the installer prints those values and you paste +them once into the site's **Admin → Shard** panel. If the sidecar is absent or the shard is +down, every shard surface degrades gracefully. --- ## Quick start -The core of a live shard is **two** things running: the **website** (site + admin) and the -**link** sidecar (the game bridge). The **servuo-plugins** get deployed into your ServUO server -root and compile at shard boot; the **Android-app** is an optional client you point at your -running website — see each repo's README. +The core of a live shard is **two** things running: the **website** (site + admin), and the +**shard side** — the sidecar plus the plugin, which the **installer** deploys in a single run on +the machine that hosts your ServUO server. The **Android-app** is an optional client you point at +your running website. ### 1. Website — the site + admin panel @@ -95,30 +107,47 @@ admin are created automatically on first boot. > from Express — `cp .env.example .env`, fill it in, then > `docker compose pull && docker compose up -d`. See the website README for the full options. -### 2. link — the uo-link sidecar +### 2. The shard side — one installer run -Prereqs: **Rust** (cargo). Standard cargo crate: +Prereqs: a **working ServUO install**, currently **stopped**, and Administrator/root. Nothing to +build and no Gitea account needed. Grab a binary and `SHA256SUMS` from the +[installer releases](https://gitea.whitlocktech.com/RunicGateway/installer/releases) — releases are +unsigned, so the checksum is the trust anchor: ```bash -git clone https://gitea.whitlocktech.com/RunicGateway/link.git -cd link/sidecar -cargo build --release # binary at target/release/uo-link-sidecar -cp sidecar.toml.example sidecar.toml # then edit (bind addrs, shared-secret token) -cargo run --release +sha256sum -c SHA256SUMS --ignore-missing +chmod +x runicgateway-installer-linux-x86_64 +sudo ./runicgateway-installer-linux-x86_64 install ``` -Then point the website at it from **Admin → Shard**: set the sidecar's base URL, WebSocket -URL, shared-secret token, and protocol version. Prebuilt Linux + Windows binaries are also -cut as a Gitea release on every merge to `main`. +```powershell +# Windows, from an elevated PowerShell +.\runicgateway-installer-windows-x86_64.exe install +``` -### 3. servuo-plugins — the shard side +It resolves a published **bundle** — an exact sidecar + plugin pair CI has checked speak the same +protocol, rather than "latest of each" — syncs the plugin overlay into your server tree, offers the +optional stock-file patch tier, installs the sidecar and registers it as a service under an +unprivileged account, and finishes by printing the four values to paste into **Admin → Shard**: -Deployed as **source** into your ServUO server root and compiled by ServUO at boot (no build -artifact, no CI). It dials the sidecar over loopback. See -[servuo-plugins](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) for deploy -steps and the compatibility notes. +``` +Base URL http://:8080 +WebSocket URL ws://:8080/ws +Protocol version 3 +Auth token 4f9c… +``` -### 4. Android-app — the native client (optional) +Keep that binary — it does not install itself, and `doctor`, `update` and `uninstall` are run from +it later. Start ServUO, then `./runicgateway-installer-… doctor` checks the deployment end to end, +through to *"has the shard actually dialed in?"* — the only check that tells a working bridge from +copied files. + +> Installing by hand is supported too — [INSTALL.md Appendix A](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md#appendix-a--installing-by-hand) +> is the same deployment with `curl`, `tar` and `systemctl`, for a host that cannot run the binary +> or for developing on the bridge from a source tree. The full operator guide is +> [`docs/installer/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md). + +### 3. Android-app — the native client (optional) Prereqs: **JDK 17** and the Android SDK. A single build works against any shard — the app prompts for your website's URL on first run. @@ -140,10 +169,11 @@ and the design contract in [`docs/android/PLAN.md`](https://gitea.whitlocktech.c ## Where to go next +- **Setting up a shard** → [`docs/installer/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md) — the operator guide: what the run asks, where it writes, the patch tier, `doctor` / `update` / `uninstall`, troubleshooting, and the by-hand path. - **Running / customizing the site** → [website README](https://gitea.whitlocktech.com/RunicGateway/website) (tech stack, API endpoints, env vars, security, branding, Swagger at `/api/docs`). - **The Android client** → [Android-app README](https://gitea.whitlocktech.com/RunicGateway/Android-app) and [`docs/android/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs) — the authoritative design contract, milestones, and the push-notification architecture. - **The bridge internals** → [docs](https://gitea.whitlocktech.com/RunicGateway/docs) — design docs, the canonical wire-protocol spec, and the integration guide. -- **Deploying the sidecar / plugin together** → [link README](https://gitea.whitlocktech.com/RunicGateway/link) and [servuo-plugins](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins). +- **Working on the sidecar or plugin** → [link README](https://gitea.whitlocktech.com/RunicGateway/link) and [servuo-plugins](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) — building from source, the loopback protocol, and the compatibility rules.
Runic Gateway · whitlocktech@gmail.com