From b8987c653bc704f789540c7694d4457b10d33bdf Mon Sep 17 00:00:00 2001 From: claude Date: Sat, 18 Jul 2026 20:59:17 +0000 Subject: [PATCH] docs: add org profile README at repo root --- README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c2aa6a6 --- /dev/null +++ b/README.md @@ -0,0 +1,129 @@ +
+ +# Runic Gateway + +**A website + game bridge for private Ultima Online (ServUO) shards.** + +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. Branding is instance-configurable; **UOMysticmoon** +is the first instance. + +[![website · build images](https://gitea.whitlocktech.com/RunicGateway/website/actions/workflows/build-images.yml/badge.svg)](https://gitea.whitlocktech.com/RunicGateway/website/actions?workflow=build-images.yml) +[![website · PR checks](https://gitea.whitlocktech.com/RunicGateway/website/actions/workflows/pr-checks.yml/badge.svg)](https://gitea.whitlocktech.com/RunicGateway/website/actions?workflow=pr-checks.yml) +[![link · release](https://gitea.whitlocktech.com/RunicGateway/link/actions/workflows/release.yml/badge.svg)](https://gitea.whitlocktech.com/RunicGateway/link/actions?workflow=release.yml) + +
+ +--- + +## The pieces + +Runic Gateway is four 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. | +| [**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. | +| [**docs**](https://gitea.whitlocktech.com/RunicGateway/docs) | Markdown | All project documentation — design docs, the wire-protocol spec, the integration guide, research. Start here when you want the *why*. | + +## How they fit together + +``` +ServUO shard ──loopback TCP,──▶ uo-link sidecar ──WebSocket + REST──▶ website backend ──▶ browser +(servuo-plugins) newline-JSON (link, Rust) bearer-auth (website, Node) same-origin + JSON / SSE +``` + +- The **shard is never exposed to the internet.** It only dials `127.0.0.1`. The **sidecar** + is the sole network-facing component, and only the website's backend talks to it. +- The **website backend** ingests a live event stream from the sidecar (logins, vitals, + economy, vendor sales, deaths, IDOC decay, staff audit…) and makes point-in-time REST + calls for rosters and character sheets. It then fans that out to browsers over + Server-Sent Events — a public channel (safe kinds only) and an admin channel (everything). +- 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. + +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. + +--- + +## Quick start + +You need **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 — see that repo's README. + +### 1. Website — the site + admin panel + +Prereqs: **Node.js 20+** and **Docker** (for MariaDB). + +```bash +git clone https://gitea.whitlocktech.com/RunicGateway/website.git +cd website + +# Start a MariaDB the backend can reach +docker run -d --name rg-db -p 3306:3306 \ + -e MARIADB_DATABASE=runic_gateway -e MARIADB_USER=runic \ + -e MARIADB_PASSWORD=devpass -e MARIADB_ROOT_PASSWORD=rootpass mariadb:11 + +# Configure + start the backend (terminal 1) +cp server/.env.example server/.env +# set DB_HOST=127.0.0.1, DB_PORT=3306, DB_USER=runic, DB_PASSWORD=devpass, +# JWT_SECRET=, ADMIN_USERNAME=admin, ADMIN_PASSWORD= +npm run install-server +npm run server # nodemon → http://localhost:3000 + +# Start the frontend (terminal 2) +npm run install-client +npm run client # Vite → http://localhost:5173 +``` + +Open **http://localhost:5173**, sign in at **`/admin/login`** with the admin credentials +you set, then flip **Maintenance → Live** on the Dashboard. Tables, defaults, and the first +admin are created automatically on first boot. + +> **Production (Docker Compose):** the website ships a production-shaped +> `docker-compose.yml` that *pulls* prebuilt `app` + `bot` images and serves the built SPA +> 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 + +Prereqs: **Rust** (cargo). Standard cargo crate: + +```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 +``` + +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`. + +### 3. servuo-plugins — the shard side + +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. + +--- + +## Where to go next + +- **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 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). + +
+Runic Gateway · whitlocktech@gmail.com +