From 5197c2c281eb3d5d7e1c4e6ec03b1939cdb52d4d Mon Sep 17 00:00:00 2001 From: wtclaude Date: Fri, 7 Aug 2026 16:05:39 -0500 Subject: [PATCH] docs(installer): lead with the installer now that it is released v0.1.0 shipped on 2026-08-07, so every doc that said "not released yet" was wrong the moment the cutover merged. - INSTALL.md: replace the pre-release status banner. The installer is the path the guide leads with; Appendix A is reframed as supported-not- deprecated, for hosts that cannot run the binary, operators who want to place files themselves, and development from a working tree. - PLAN.md: status is Shipped, both cutover gates recorded as met (incl. the Windows 1053 handshake bug the real SCM run found), Phase 5 table and 5.4 closed out. - README.md: point anyone setting up a shard at INSTALL.md first. - link/link-README.md: mark the pre-split snapshot as historical, so its deploy.ps1 instructions stop reading as the setup path. Co-Authored-By: Claude --- README.md | 6 ++- installer/INSTALL.md | 35 +++++++-------- installer/PLAN.md | 105 ++++++++++++++++++++++++------------------- link/link-README.md | 7 +++ 4 files changed, 87 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 6df81ff..7836175 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ installer/ docs for the installer that deploys a shard's bridge components ci/ cross-cutting CI/quality notes ``` +**Setting up a shard?** [`installer/INSTALL.md`](installer/INSTALL.md) is the operator guide, and +the installer is the supported path: one binary deploys the plugin overlay, installs the uo-link +sidecar as a service, and hands you the values the website needs. + ### `website/` | Doc | What it covers | |---|---| @@ -54,7 +58,7 @@ ci/ cross-cutting CI/quality notes ### `installer/` | Doc | What it covers | |---|---| -| [INSTALL.md](installer/INSTALL.md) | **Operator guide** — installing Runic Gateway on a ServUO shard, connecting it to the website, and diagnosing it. Includes the by-hand path, which works today | +| [INSTALL.md](installer/INSTALL.md) | **Start here to set up a shard** — the installer deploys the plugin overlay and the uo-link sidecar, registers the service, and connects it to the website. Appendix A is the same thing by hand, still supported | | [PLAN.md](installer/PLAN.md) | Installer design of record — phases, locked decisions, the bundle/compat-matrix model | ## Provenance diff --git a/installer/INSTALL.md b/installer/INSTALL.md index 4421bcb..26993b5 100644 --- a/installer/INSTALL.md +++ b/installer/INSTALL.md @@ -3,25 +3,15 @@ Operator guide for the **Runic Gateway installer** — the tool that takes a working ServUO installation and connects it to a Runic Gateway website. -> **Status: the installer binary is not released yet.** +> **The installer is the supported way to set this up.** Download one binary, run `install`, paste +> four values into your website. It deploys the plugin overlay, installs the uo-link sidecar and +> registers it as a service, and gives you [`doctor`, `update` and `uninstall`](#7-day-two) +> afterwards. Start at [§1](#1-download-and-verify). > -> Phases 1 to 3 are built and live on the installer repo's `edge` branch: the installer core -> (bundle resolution, ServUO detection, the overlay sync, `install.json`), the sidecar half (the -> binary, its config, its service, and the token handoff), and the -> [patch tier](#4-the-patch-tier-optional). `install` is therefore complete; what is still missing -> is [`doctor`, `update` and `uninstall`](#7-day-two), each of which reports which phase it arrives -> in rather than failing as though you had mistyped it. The first release is being cut from that -> branch now. -> -> Everything it installs *is* released and published — the sidecar, the plugin overlay, and the -> [bundle manifest](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/main/bundles/current.json) -> that names the checked combination of the two. This guide is the operator-facing contract those -> phases build to, and it is written first on purpose: it is the specification of what the run -> looks like, what it asks, where it writes, and what it prints. -> -> **You can install today without it** — [Appendix A](#appendix-a--installing-by-hand) is the same -> deployment done by hand, with the commands verified against the current releases. When the binary -> ships, Appendix A stays as the reference for what it does under the hood. +> [Appendix A](#appendix-a--installing-by-hand) is the same deployment done by hand. It is +> **supported, not deprecated** — use it on a host that cannot run the binary, when you want to +> place things yourself, or when you are developing on the bridge and installing from a working +> tree rather than a release. It is also the reference for what the installer does under the hood. > > Design of record: [PLAN.md](PLAN.md). @@ -642,8 +632,13 @@ release tarball is gone, and the report tells you to diff against them. ## Appendix A — installing by hand -This is what the installer automates. It works today, on the current releases, and is the fallback -whenever you would rather not run an unsigned binary. +This is what the installer automates, done by hand. It is a **supported path**, not a deprecated +one — reach for it when the host cannot run the binary, when you would rather not run an unsigned +one, when you want to place every file yourself, or when you are developing on the bridge and +installing from a working tree instead of a release. It is also the reference for what +[§2](#2-run-it) does under the hood. + +For a normal shard, [the installer](#1-download-and-verify) is fewer steps and checks more. Throughout: `` is your ServUO root, and **the shard is stopped**. diff --git a/installer/PLAN.md b/installer/PLAN.md index 36ef520..a6b7a22 100644 --- a/installer/PLAN.md +++ b/installer/PLAN.md @@ -1,31 +1,43 @@ # Runic Gateway Installer — plan -Status: **Phases 1 to 4 built, on `edge`.** Phase 0's prerequisites all landed, the installer repo -publishes the bundle manifest, and [`INSTALL.md`](INSTALL.md) specified the operator-facing run -before the binary existed. The crate now implements the installer core (bundle resolution, ServUO +Status: **Shipped.** All five phases are built, the `edge → main` cutover merged on 2026-08-07 +([installer#17](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/17)), and it cut the +first release — +[`v0.1.0`](https://gitea.whitlocktech.com/RunicGateway/installer/releases/tag/v0.1.0), publishing +`linux-x86_64`, `linux-aarch64` and `windows-x86_64.exe` plus `SHA256SUMS`. The binary does +everything [`INSTALL.md`](INSTALL.md) describes: the installer core (bundle resolution, ServUO detection and validation, the overlay sync, `install.json` — [Phase 1 as built](#phase-1--installer-core)), the sidecar half (binary, config, service, token handoff — [Phase 2 as built](#phase-2--uo-link-install-and-service)), the patch tier (the rung ladder, the unsupported-version path, the cached patch set — [Phase 3 as built](#phase-3--patch-tier-opt-in)), -and the day-two commands `doctor`, `update` and `uninstall` ([Phase 4 as -built](#phase-4--diagnostics-and-updates)). All four are on the `edge` branch, not `main`, so no -half-capable binary is released; the binary on `edge` now does everything `INSTALL.md` describes. +the day-two commands `doctor`, `update` and `uninstall` ([Phase 4 as +built](#phase-4--diagnostics-and-updates)), and the packaging polish that gated the cutover +([Phase 5](#phase-5--packaging-polish)). -**Phase 5 comes before the cutover, not after it** (org lead, 2026-08-05). The earlier order — cut -the release, then polish — would publish a first release that is immediately superseded, and the -release layout is exactly what Phase 5 changes. So the `edge → main` cutover is now gated on two -things: +**The installer is now the supported way to set a shard up**, and the operator guide leads with it. +`INSTALL.md`'s [Appendix A](INSTALL.md#appendix-a--installing-by-hand) remains supported rather than +deprecated — it is the path for a host that cannot run the binary, for an operator who wants to +place files themselves, and for developing on the bridge from a working tree. -1. **Phase 5, packaging polish** (§5) — the last work before a first release, rather than the first - work after it. Its scope is now settled: **no `.deb` and no MSI** (§5.1 — both would give the - service, its unit and its user a second owner), **Linux `aarch64` for both components** (§5.2), - **a backup of what an upgrade overwrites** (§5.3), and the docs a first release invalidates - (§5.4). -2. **The Windows SCM half being verified on a real host.** systemd registration has now been run for - real (see [Phase 2 as built](#phase-2--uo-link-install-and-service)), and doing it found a bug no - amount of unit testing had. `sc create`, the virtual service account, the failure actions and the - token-file ACL have **still never been executed** — that path needs one elevated Windows run, and - nothing should be released while the only untested code is the half that registers a service. +**Phase 5 came before the cutover, not after it** (org lead, 2026-08-05). The earlier order — cut +the release, then polish — would have published a first release immediately superseded by the next, +and the release layout is exactly what Phase 5 changed. Both cutover gates were met before the +merge: + +1. **Phase 5, packaging polish** (§5) — scope settled and built: **no `.deb` and no MSI** (§5.1 — + both would give the service, its unit and its user a second owner), **Linux `aarch64` for both + components** (§5.2), **a backup of what an upgrade overwrites** (§5.3), and the docs a first + release invalidates (§5.4). +2. **The Windows SCM half verified on a real host**, 2026-08-07. It was worth insisting on: the + first real `sc start` failed with **1053**, because the SCM waits ~30s for a handshake a plain + console program cannot perform. Fixed in the sidecar + ([link#29](https://gitea.whitlocktech.com/RunicGateway/link/pulls/29), v1.2.0) and verified end + to end against a live service — 13/13 checks, start in 1s, `RUNNING`, `/health` served, service + log written, clean stop — + with [installer#16](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/16) making the + installer diagnose 1053 as a handshake rather than blaming the config. systemd registration was + verified separately on 2026-08-05 against a real privileged systemd container, and that run + likewise found a bug no unit test had. This document is the design of record; it supersedes the informal overview it grew out of, which described a ServUO integration that does not match how `servuo-plugins` actually ships (see @@ -468,12 +480,12 @@ Repo work that must land before an installer can exist. might exist; it is the specification of what the run asks, where it writes, what it prints, and what the operator does next. Phase 1–4 implement it. - - **It is useful before the installer exists.** Appendix A is the same deployment done by hand — - bundle fetch, tarball verify + overlay copy, the optional patch tier, `--print-config` - provisioning, and a systemd unit / `sc create` service — composed from the released artifacts' - actual contents and the sidecar's config and CLI source rather than from memory. That appendix - doubles as **Phase 1's acceptance test**: walking it end to end on a real shard is what proves - the automated path has nothing left to discover. + - **It was useful before the installer existed, and outlives it.** Appendix A is the same + deployment done by hand — bundle fetch, tarball verify + overlay copy, the optional patch tier, + `--print-config` provisioning, and a systemd unit / `sc create` service — composed from the + released artifacts' actual contents and the sidecar's config and CLI source rather than from + memory. That appendix doubles as **Phase 1's acceptance test**: walking it end to end on a real + shard is what proves the automated path has nothing left to discover. - **The installer does not install itself.** §5's `runicgateway doctor` sketch implied a name on `PATH`; nothing places one there, and adding self-installation would give the tool a second lifecycle to manage. The guide names the downloaded artifact, says to keep it, and shortens it @@ -889,20 +901,20 @@ MSI, arm64 cross build, optional automated backup before upgrade — and the org on 2026-08-05: **two of the four are dropped rather than deferred**, because what stops them is an ownership conflict that does not improve with time, and two are built. -**It runs before the `edge → main` cutover rather than after it.** The original order assumed the +**It ran before the `edge → main` cutover rather than after it.** The original order assumed the cutover would cut a v1 and packaging would follow as a v1.x — but this phase changes the *release -layout* (§3), so shipping first would mean a first release that is superseded by the next one, and +layout* (§3), so shipping first would have meant a first release superseded by the next one, and operators who downloaded a bare binary being told to re-download a package. Deferring the cutover -costs nothing: nothing is published from `edge`, and the guide's Appendix A is the supported path -meanwhile. +cost nothing: nothing was published from `edge`, and the guide's Appendix A was the path meanwhile +(and remains supported now that it is no longer the default). | Item | Decision | State | |---|---|---| | `.deb` for uo-link | **Dropped** (§5.1) | — | | Windows MSI | **Dropped** (§5.1) | — | -| arm64 cross build | **Build** — Linux `aarch64`, both components (§5.2) | In review: [installer#9](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/9), [link#26](https://gitea.whitlocktech.com/RunicGateway/link/pulls/26), [installer#10](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/10); step 3 waits on link's first arm64 release | -| Backup before upgrade | **Build** — on by default, scoped to what a run overwrites (§5.3) | In review: [installer#11](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/11) | -| Docs the release invalidates | **Do** (§5.4) | Pending | +| arm64 cross build | **Build** — Linux `aarch64`, both components (§5.2) | ✅ Merged — [installer#9](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/9), [link#26](https://gitea.whitlocktech.com/RunicGateway/link/pulls/26), [installer#10](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/10) | +| Backup before upgrade | **Build** — on by default, scoped to what a run overwrites (§5.3) | ✅ Merged — [installer#11](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/11) | +| Docs the release invalidates | **Do** (§5.4) | ✅ Done — `INSTALL.md` took the `aarch64` and backup content pre-cutover; the status rewrites landed after it | #### 5.1 What ships is plain binaries: no `.deb`, no MSI @@ -1024,20 +1036,23 @@ that is still downloadable, and the noise would bury the two files that matter. Not optional, and grouped here because a first release is the moment these are read for the first time by someone who was not in the room: -- **`installer/README.md`'s status table still says Phase 1 is built and Phase 2 is next**, four - phases later. It is the first thing a visitor to the repo reads. -- **`INSTALL.md`** gains the `aarch64` download lines, the backup behaviour and `--no-backup`. -- **This file:** §3 loses the `.deb` and gains the `aarch64` assets, §2.6's arm64 bullet is now - historical, and §7.1's example bundle grows the third asset key. +- **`installer/README.md`'s status table** — the first thing a visitor to the repo reads, and it + described a tool that was neither finished nor released. Rewritten at the cutover. +- **`INSTALL.md`** gained the `aarch64` download lines, the backup behaviour and `--no-backup` + before the cutover, and its status banner afterwards: the installer is the path the guide leads + with, Appendix A the supported manual one. +- **This file:** §3 lost the `.deb` and gained the `aarch64` assets, §2.6's arm64 bullet is now + historical, and §7.1's example bundle grew the third asset key. -#### Cutover entry criteria +#### Cutover entry criteria — met, 2026-08-07 -The `edge → main` cutover is gated on this phase **and** on the outstanding **Windows SCM -verification** (see the status header and [Phase 2 as built](#phase-2--uo-link-install-and-service)). -The second is not busywork: running the systemd half for real found a bug that unit tests could not, -and `sc create` remains the only code in the crate that has never executed. The smoke script at the -workspace root was run on 2026-08-05 and stopped at its first check — an unelevated shell — so -nothing in that half has executed yet; it needs one run from an elevated PowerShell. +Both gates were satisfied before +[installer#17](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/17) merged: this phase, +and the **Windows SCM verification** (see the status header and +[Phase 2 as built](#phase-2--uo-link-install-and-service)). The second was not busywork — it failed +on its first real run with 1053 and needed a sidecar fix before it passed, exactly as running the +systemd half for real had turned up a bug unit tests could not. The bundle the release shipped +against was `2026.08.07`: link `v1.2.1`, overlay `v0.2.0`, both declaring protocol 3. --- diff --git a/link/link-README.md b/link/link-README.md index d678fe7..d21900e 100644 --- a/link/link-README.md +++ b/link/link-README.md @@ -1,5 +1,12 @@ # uo-link +> **Historical snapshot**, from before the bridge was split into +> [`RunicGateway/link`](https://gitea.whitlocktech.com/RunicGateway/link) (sidecar) and +> [`RunicGateway/servuo-plugins`](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) +> (plugin). Kept for the architecture notes below. **To set a shard up, use +> [installer/INSTALL.md](../installer/INSTALL.md)** — `deploy.ps1` as described here is a developer +> tool, not the operator path. + ServUO ⇄ Rust sidecar bridge. The shard emits newline-delimited JSON over a loopback TCP socket; the sidecar owns the WebSocket the website consumes. ```