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

docs: bring the org profile up to current state

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
claude
2026-08-07 16:38:35 -05:00
parent d1eec6b7a0
commit f98005eec0
1 changed files with 57 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@@ -6,9 +6,13 @@
Runic Gateway is a self-hostable platform that gives a UO shard a public site, wiki, 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 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 status, economy, IDOCs, player activity, per-character sheets, a player-vendor marketplace,
control commands back into the game. Players get the same public content and self-service and a bestiary built from the shard's own spawn tables, while staff push control commands
on the web **or** a native Android app. Branding is instance-configurable. 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.
</div> </div>
@@ -16,13 +20,14 @@ on the web **or** a native Android app. Branding is instance-configurable.
## The pieces ## 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 | | 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. | | [**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. | | [**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. | | [**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. | | [**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*. | | [**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 - 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 is what authorizes character reads. Staff can push town-crier messages and control
commands back into the game. 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 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. **admin-managed in the database**, not env — the installer prints those values and you paste
If the sidecar is absent or the shard is down, every shard surface degrades gracefully. 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 ## Quick start
The core of a live shard is **two** things running: the **website** (site + admin) and the 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 **shard side** — the sidecar plus the plugin, which the **installer** deploys in a single run on
root and compile at shard boot; the **Android-app** is an optional client you point at your the machine that hosts your ServUO server. The **Android-app** is an optional client you point at
running website — see each repo's README. your running website.
### 1. Website — the site + admin panel ### 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 > 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. > `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 ```bash
git clone https://gitea.whitlocktech.com/RunicGateway/link.git sha256sum -c SHA256SUMS --ignore-missing
cd link/sidecar chmod +x runicgateway-installer-linux-x86_64
cargo build --release # binary at target/release/uo-link-sidecar sudo ./runicgateway-installer-linux-x86_64 install
cp sidecar.toml.example sidecar.toml # then edit (bind addrs, shared-secret token)
cargo run --release
``` ```
Then point the website at it from **Admin → Shard**: set the sidecar's base URL, WebSocket ```powershell
URL, shared-secret token, and protocol version. Prebuilt Linux + Windows binaries are also # Windows, from an elevated PowerShell
cut as a Gitea release on every merge to `main`. .\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 Base URL http://<shard-host>:8080
[servuo-plugins](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) for deploy WebSocket URL ws://<shard-host>:8080/ws
steps and the compatibility notes. 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 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. 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 ## 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`). - **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 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. - **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.
<div align="center"> <div align="center">
<sub>Runic Gateway · whitlocktech@gmail.com</sub> <sub>Runic Gateway · whitlocktech@gmail.com</sub>