wtclaude
b7d1bbbc78
Every failed `sc.exe start` was reported with "a service that exits immediately usually cannot read its config", which for the one error code that actually occurs is the wrong place to look. 1053 is the SCM giving up after 30 seconds waiting for the process to identify itself; the process started fine and is very likely serving traffic. A reader who follows the old sentence goes and stares at a config file that is correct. Replace it with windows_start_failure(), which names the real cause per code: - 1053: a handshake failure, almost always a sidecar older than v1.2.0 (the first release that speaks the SCM protocol). Says how to check the version, and how to prove the binary is healthy by running it in the foreground. - 1069: the virtual service account was refused, which is local policy rather than a bad credential, and points at INSTALL.md Appendix A4. - anything else: does not guess, and hands over the event log, `sc query` for the service's own exit code, and the foreground command. Pure and tested on both platforms, like windows_bin_path above it, so the text is covered on the Linux CI runner that never sees an SCM. Co-Authored-By: Claude <noreply@anthropic.com>
Runic Gateway installer
A single-binary deployment tool that takes a stock ServUO installation and configures it for Runic Gateway: deploys the shard plugin overlay, optionally applies the stock-file patch tier, installs the uo-link sidecar and registers it as a service, records what it deployed, and hands the operator the four values that connect the website to the shard.
┌──────────────────────────────────────────┐
│ Runic Gateway installer (>>> HERE <<<)│
└───────────────┬──────────────────────────┘
│ deploys
┌───────────────┴────────────────┐
▼ ▼
ServUO integration uo-link sidecar
overlay sync + opt-in patch tier binary + config + service
(RunicGateway/servuo-plugins) (RunicGateway/link)
It is a deployment tool, not a hosted bootstrapper — no curl | bash, no
installer service. Artifacts are downloaded from a Gitea release page and run.
It also does not replace ServUO startup behavior. ServUO keeps running through its existing release/start scripts; the installer never writes a launcher and never restarts the shard.
Status
Phases 1 to 4 are built, on the edge branch. Nothing is released yet.
The binary does everything
installer/INSTALL.md
describes: bundle resolution, ServUO detection and validation, the overlay sync,
the opt-in patch tier, install.json, the uo-link sidecar and its service, the
token handoff, and doctor / update / uninstall.
The design of record is
installer/PLAN.md
in the docs repo: phases, locked decisions, and the Phase 0 prerequisites in other
repos (a servuo-plugins release workflow, a non-interactive config read-back in
link, and the bundle-manifest CI here), all of which have landed —
bundles/current.json names the current protocol-checked
sidecar + overlay combination, recomposed on every component release and nightly
(see bundles/README.md).
| Phase | State |
|---|---|
| 0 — prerequisites in the other repos | ✅ merged |
1 — installer core: bundle resolution, ServUO detection, overlay sync, install.json |
✅ on edge |
| 2 — uo-link install + service registration | ✅ on edge |
| 3 — the opt-in stock-file patch tier | ✅ on edge |
4 — doctor, update, uninstall |
✅ on edge |
5 — packaging polish: Linux aarch64, backup before overwrite |
in progress |
Why edge: release.yml publishes an installer binary on every push to
main, so nothing lands there until the whole tool is worth handing to an
operator. The edge → main cutover cuts the first release. PRs into edge run
the same gates as PRs into main.
What the cutover is waiting on, per PLAN.md §5:
- Phase 5, packaging polish — deliberately before the first release rather
than after it, because it changes the release layout, and shipping first would
mean a first release immediately superseded by the next. There is no
.deband no MSI: both would give the sidecar binary, its service unit and its service account a second owner beside this tool. - The Windows SCM half verified on a real host.
sc create, the virtual service account, the failure actions and the token-file ACL have never been executed anywhere. Running the systemd half for real is what turned up a bug no unit test had, so this is not a formality.
Until the cutover, the way to install is by hand —
INSTALL.md Appendix A
is the same deployment done with curl, tar and systemctl.
Related repos
| Repo | What |
|---|---|
this — RunicGateway/installer |
The installer (Rust, one binary per OS). |
| RunicGateway/link | The uo-link sidecar — the network-facing half of the game bridge. Installed and service-registered by this tool. |
| RunicGateway/servuo-plugins | The C# ServUO plugin — deployed as source (overlay/) and compiled by ServUO at boot. Synced into the server tree by this tool. |
| RunicGateway/website | The public site and admin panel. The installer never contacts it — it prints values for Admin → Shard. |
| RunicGateway/docs | All project documentation, including the installer plan. |
Commands
| Command | What it does |
|---|---|
install |
Detect and validate the ServUO root, sync the overlay, optionally apply patches, install uo-link + service, write install.json, print the token handoff. |
doctor |
Diagnose an installed deployment end to end — through to "has a shard actually dialed in?", the only check that distinguishes a working bridge from copied files. |
update |
Resolve the current bundle manifest, then update the sidecar (replace + restart) and the overlay (re-sync + tell the operator to restart ServUO). |
uninstall |
Remove only what the installer exclusively owns. It never edits the ServUO tree — it prints the overlay files to delete and the patch hunks to revert, and leaves that call to the operator. |
Design constraints worth knowing up front
- Releases are unsigned.
SHA256SUMSis the trust anchor; SmartScreen and Gatekeeper warnings are expected and documented. The installer nonetheless verifies the SHA256 of everything it downloads and refuses on mismatch. - Composition comes from a published bundle manifest, not from "latest of
each". CI names an exact, protocol-checked combination of sidecar and overlay
versions;
--bundle <tag>pins one for a reproducible install. A new component release regenerates JSON, not this binary. - The base install must complete without the patch tier. The patch tier edits stock ServUO files, most real shards are hand-modified, and unverified ServUO versions skip it with a warning rather than being patched blind.
- A successful copy is not a working bridge. ServUO ignores the script build's
exit code and silently reloads the previous
Scripts.dll, so diagnostics verify post-boot state rather than trusting a clean boot. - What a run overwrites is copied first. Every
.csfile the overlay owns is replaced unconditionally, so an operator's edit to one is saved underbackups/<timestamp>/before it goes. Restoring is theirs to do — this tool will not put an old file back over a newer release. - The audience is public — any ServUO operator, not only shards we run.
Build & run
A standard cargo project, with the crate at the repo root:
cargo build --release
cargo run -- --help
cargo run -- install --servuo /path/to/ServUO --verify # dry run: writes nothing
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
RUNICGATEWAY_STATE_DIR relocates everything the installer writes — state,
data, and the sidecar binary (normally /etc/runicgateway, /var/lib/runicgateway
and /usr/bin, or %ProgramData%\RunicGateway and %ProgramFiles%\RunicGateway).
It also suppresses service registration, since there is no such thing as a
relocated systemd unit or Windows service. That is how a full run is tested
without root.
Two layout notes that look odd until you know why:
- The library target is
rgdeploy, notrunicgateway_installer. Windows' UAC installer detection refuses to launch an unsigned executable whose file name containsinstall(os error 740), and Cargo names test harnesses after their target — so a target under that name makescargo testunrunnable on Windows. The published binary keeps its documented name;[[bin]] test = falsekeeps Cargo from building a harness under it. Expect a UAC prompt when running the built binary on Windows; it needs Administrator anyway. Cargo.lockis committed, and CI builds--locked.
See CONTRIBUTING.md for the development setup, the local checks CI will run, and the branch/PR workflow.
License
Runic Gateway is free software, licensed under the GNU General Public License v3.0 or later — see LICENSE.md.
Copyright (C) 2026 Runic Gateway
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version. It is distributed WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
Contributions are welcome — please read CONTRIBUTING.md (note the AI-usage disclosure requirement) and our Code of Conduct. Report vulnerabilities privately per SECURITY.md.