From 48b16dc70ecf66e0e9be3e2653633ba5070ef4ae Mon Sep 17 00:00:00 2001 From: wtclaude Date: Fri, 7 Aug 2026 16:05:56 -0500 Subject: [PATCH] docs: make the installer the documented way to deploy the overlay "## Deploy" led with deploy.ps1 and mentioned the installer only afterwards, which is backwards now that the installer is released. - Deploy leads with the installer, with the by-hand overlay copy (INSTALL.md Appendix A2) as the supported alternative. - deploy.ps1 gets its own subsection as the developer path: it deploys from a working tree, which is the one thing the installer cannot do, and it installs no sidecar and checks no protocol pairing. - CONTRIBUTING: note that changes reach shards through a release, so a change that only works when deploy.ps1 copies it does not ship. Co-Authored-By: Claude --- CONTRIBUTING.md | 7 +++++++ README.md | 41 +++++++++++++++++++++++++++++++---------- 2 files changed, 38 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4b975f..364b194 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,13 @@ under `overlay/` (or `patches/` for changes to stock ServUO files) and deploy: .\deploy.ps1 -ServerPath C:\path\to\servuo ``` +`deploy.ps1` deploys from *this working tree*, which is what you want while +developing. It is not how a shard is set up: operators run the +[Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer), +which syncs the released overlay tarball and installs the sidecar alongside it. +Changes here reach shards through a [release](README.md#releases), so a change +that only works when `deploy.ps1` copies it is a change that does not ship. + - `overlay/` — copied over an install (the only thing `deploy.ps1` deploys). - `patches/` — unified diffs against stock ServUO for files we must modify. - `tools/` — never deployed: test scaffolding and stub sidecars. diff --git a/README.md b/README.md index 91aac1a..a35e457 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ integration guide, protocol spec, research — with full history preserved). | `overlay/` | Mirrors the ServUO server root. Everything here — and **only** this — copies over an install. | | `patches/` | Unified diffs against stock ServUO for files we must modify rather than add. | | `tools/` | Never deployed. Test scaffolding (C# probes + PowerShell stub sidecars) and anything else that must not reach a server. | -| `deploy.ps1` | Copies `overlay/` into a server root. `-Verify` diffs instead of writing. | +| `deploy.ps1` | **Developer tool** — copies `overlay/` from this working tree into a server root. `-Verify` diffs instead of writing. Operators use the [installer](https://gitea.whitlocktech.com/RunicGateway/installer); see [Deploy](#deploy). | | `overlay.toml` | Release metadata: the wire-protocol version this overlay speaks, and its ServUO compatibility. Read by CI into the release manifest — see [Releases](#releases). | | `.gitea/workflows/release.yml` | Publishes `runicgateway-overlay-.tar.gz` on every merge to `main`. | | [INTEGRATION.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md) | **Website integration guide** — the WebSocket feed, REST endpoints, auth, event catalog, and examples. | @@ -39,14 +39,17 @@ Anything under `overlay/` is authoritative. Do not edit files in the server tree ## Sidecar & deployment The Rust sidecar is the other half of the bridge and lives in **[RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link)**. -The two are deployed **together** but built **independently**: +The two are deployed **together** — by the +[installer](https://gitea.whitlocktech.com/RunicGateway/installer), in one run — but built +**independently**: -- **This plugin** is deployed as *source* — `deploy.ps1` copies `overlay/` into the ServUO server - root, and ServUO compiles it at boot (`Scripts.csproj`; see [Phase 0](#phase-0--what-it-fixes)). - There is **no CI build** — it cannot be compiled standalone without the ServUO reference - assemblies. CI does publish a *source* tarball for the installer to fetch; see +- **This plugin** is deployed as *source*: `overlay/` is copied into the ServUO server root and + ServUO compiles it at boot (`Scripts.csproj`; see [Phase 0](#phase-0--what-it-fixes)). There is + **no CI build** — it cannot be compiled standalone without the ServUO reference assemblies. CI + publishes a *source* tarball, which is what the installer fetches and syncs; see [Releases](#releases). -- **The sidecar** is a standalone Rust binary, released from its own repo. +- **The sidecar** is a standalone Rust binary, released from its own repo and installed from that + release. The **only** coupling is the loopback JSON protocol (the shard dials out to the sidecar on `127.0.0.1`). Compatibility is a **protocol** concern, not a build-order one: keep the event/command @@ -57,14 +60,32 @@ without the sidecar running. ## Deploy +**On a shard, use the [Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer).** +One binary syncs this overlay from the release tarball below, offers the patch tier, installs the +uo-link sidecar as a service, and prints the values your website needs — cross-platform, with a +`doctor` afterwards to tell a copied file from a working bridge: + +```bash +sudo ./runicgateway-installer-linux-x86_64 install +``` + +Guide: [installer/INSTALL.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md). +To place the overlay yourself instead — a host that cannot run the binary, or you want to see every +file land — [Appendix A2](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md#a2-deploy-the-plugin-overlay) +is the same copy done by hand, and stays supported. + +### `deploy.ps1` — the developer path + +`deploy.ps1` deploys from a **working tree**, which is what you want while writing plugin code and +is the one thing the installer cannot do (it deploys from a release): + ```powershell .\deploy.ps1 -ServerPath -Verify # show what would change .\deploy.ps1 -ServerPath # write ``` -`deploy.ps1` is the **developer-facing** tool and stays that way. Operators get the -[Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer), which does the -same sync cross-platform from the release tarball below. +It is Windows-only and stays developer-facing; it never installs the sidecar, registers a service, +or checks the protocol pairing. Nothing shipped to an operator depends on it. ## Releases