RunicGateway/servuo-plugins
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: make the installer the documented way to deploy the overlay

Browse Source 
"## 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 <noreply@anthropic.com>
This commit is contained in:
claude
2026-08-07 16:05:56 -05:00
parent c045bdd566
commit 48b16dc70e
2 changed files with 38 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
CONTRIBUTING.md
View File

@@ -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.

41
README.md
View File

@@ -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-<ver>.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 <servuo> -Verify # show what would change
.\deploy.ps1 -ServerPath <servuo> # 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