wtclaude
6c49217e9c
backup.rs justified skipping the sidecar's database on two claims. Protocol 4 falsifies one and reveals the other was already wrong. It said the database is safe because store.rs creates every table IF NOT EXISTS. That held only while every schema change added a whole table — which, up to and including Protocol 3.0, every one of them did. Protocol 4 adds a COLUMN to a table that already exists, which IF NOT EXISTS cannot do, so link now carries a real migration. A run can change the database's structure, not only its contents. It also said every table holds state the sweeps repopulate. `events` does not: it is never pruned, and the website backfills what it missed from GET /history on every reconnect. So a lost database costs the gap-recovery window for whatever happened while the site was down. That claim was untrue before this workstream existed. The behaviour does not change — the database is still not copied — because the argument against backing up unbounded bulk survives both corrections: `events` grows without limit, the migration is transactional and additive, and the website holds its own durable copy of everything already ingested. Only the reasoning was wrong, and a wrong reason left in place is what lets the next person extend it to a case it never covered. Whether that unbounded table should be pruned or protected belongs to link, on its own merits, rather than being settled inside a backup policy. No logic change; docs only. Refs: docs/website/TEAMS.md Part 12 Phase 1 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.
Install a shard with it
Grab a binary and SHA256SUMS from the
releases page,
verify the checksum, and run it as Administrator/root against a stopped shard:
sha256sum -c SHA256SUMS --ignore-missing
chmod +x runicgateway-installer-linux-x86_64
sudo ./runicgateway-installer-linux-x86_64 install
# Windows, from an elevated PowerShell
.\runicgateway-installer-windows-x86_64.exe install
It ends by printing the four values to paste into Admin → Shard on your site.
The full operator guide — what it asks, where it writes, the patch tier, day-two
commands and troubleshooting — is
installer/INSTALL.md.
Prefer to place everything yourself, or on a host that cannot run the binary?
INSTALL.md Appendix A
is the same deployment done with curl, tar and systemctl, and stays
supported.
Status
Released. All five phases are built and the edge → main cutover (#17) cut
the first release, v0.1.0,
publishing linux-x86_64, linux-aarch64 and windows-x86_64.exe with
SHA256SUMS.
| Phase | State |
|---|---|
| 0 — prerequisites in the other repos | ✅ merged |
1 — installer core: bundle resolution, ServUO detection, overlay sync, install.json |
✅ released |
| 2 — uo-link install + service registration | ✅ released |
| 3 — the opt-in stock-file patch tier | ✅ released |
4 — doctor, update, uninstall |
✅ released |
5 — packaging polish: Linux aarch64, backup before overwrite |
✅ released |
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).
main publishes. release.yml cuts a release from every push to main, which
is why the crate was integrated on edge until it was worth handing to an
operator. Both cutover gates were met first: Phase 5 (its scope settled as no
.deb and no MSI — either would give the sidecar binary, its service unit and
its service account a second owner beside this tool), and the Windows SCM half
verified on a real host. That second one earned its place: sc start failed
with 1053 on its first real run and needed a sidecar fix (link#29) before it
passed 13/13.
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.