installer/README.md

# 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`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/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`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/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`](bundles/current.json) names the current protocol-checked
sidecar + overlay combination, recomposed on every component release and nightly
(see [`bundles/README.md`](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:

1. **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 `.deb`
   and no MSI: both would give the sidecar binary, its service unit and its
   service account a second owner beside this tool.
2. **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](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md#appendix-a--installing-by-hand)
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](https://gitea.whitlocktech.com/RunicGateway/link) | The **uo-link sidecar** — the network-facing half of the game bridge. Installed and service-registered by this tool. |
| [RunicGateway/servuo-plugins](https://gitea.whitlocktech.com/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](https://gitea.whitlocktech.com/RunicGateway/website) | The public site and admin panel. The installer never contacts it — it prints values for Admin → Shard. |
| [RunicGateway/docs](https://gitea.whitlocktech.com/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.** `SHA256SUMS` is 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 `.cs` file the overlay owns is
  replaced unconditionally, so an operator's edit to one is saved under
  `backups/<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:

```bash
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`, not `runicgateway_installer`.** Windows' UAC
  installer detection refuses to launch an unsigned executable whose file name
  contains `install` (`os error 740`), and Cargo names test harnesses after their
  target — so a target under that name makes `cargo test` unrunnable on Windows.
  The published binary keeps its documented name; `[[bin]] test = false` keeps
  Cargo from building a harness under it. Expect a UAC prompt when running the
  built binary on Windows; it needs Administrator anyway.
- **`Cargo.lock` is committed**, and CI builds `--locked`.

See [CONTRIBUTING.md](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](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](CONTRIBUTING.md) (note
the **AI-usage disclosure** requirement) and our
[Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities privately per
[SECURITY.md](SECURITY.md).