docs(installer): add the operator install guide (Phase 0.4) #87

wtclaude · 2026-08-04T16:39:46Z

wtclaude commented

2026-08-04 16:39:46 +00:00

What & why

Closes the last Phase 0 item of the installer plan: docs/installer/INSTALL.md, the operator-facing guide.

It is written before the installer binary on purpose. Everything it installs is already released (0.1–0.3: the overlay tarball, the sidecar with --print-config, and the bundle manifest), so the guide is not speculation about a tool that might exist — it is the specification of what the run asks, where it writes, what it prints, and what the operator does next. Phases 1–4 implement it.

It is useful today. 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. 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.

Contents: what gets installed and what it deliberately does not do · prerequisites · download + checksum verification (the artifacts are unsigned, so this is the trust anchor) · the run, its prompts and its flag surface · where everything lands on both OSes · the opt-in patch tier and exactly what skipping it costs · the token handoff mapped onto the Admin → Shard fields · how to verify the bridge actually works rather than merely installed · doctor/update/uninstall · a troubleshooting table · appendices for sidecar.toml and the Bridge.cfg settings most shards want to review.

Four things writing it settled (now recorded in `PLAN.md`)

The installer does not install itself. §5's runicgateway doctor sketch implied a name on PATH; nothing places one there. Day-two commands run from the downloaded binary.
The flag surface. --servuo, --patches/--no-patches, --host, --site-url, --yes join the --verify/--bundle/--purge the plan already named, so every prompt has a non-interactive equivalent and an unattended install is expressible.
A modified Config/Bridge.cfg is reported, not overwritten — one deliberate deviation from deploy.ps1. Its overwrite-on-hash-differs rule is right for a developer redeploying their own tree and wrong for an operator: an update would silently revert LinkUrl, PublicConnectAddress, sweep intervals — the shard's whole bridge configuration. install.json's recorded hashes are what make "the operator edited this" distinguishable from "the overlay moved on". Every .cs file and Scripts.csproj still overwrite unconditionally.
Remote-website deployments. [web] bind defaults to loopback, which only works when the site runs on the shard host. Widen it, firewall it to the website's address, and front it with TLS or a VPN off a trusted network — the token is always required but travels as a plain bearer over HTTP. [shard] bind stays on loopback, because that socket carries inbound commands into the game.

Also adds the missing installer/ section to the docs index (it was never added when PLAN.md landed), and refreshes two stale examples in PLAN.md — the doctor sample's overlay file count (30 → 24, the real count) and sidecar version (0.3.0 → 1.1.0).

How it was tested

Documentation only — no code. Every value in the guide was checked against the source rather than written from memory:

CLI flags, --print-config JSON keys, --version output and the UOLINK_* environment overrides against link/sidecar/src/{cli,config,main}.rs; the bind/db defaults and the config-relative [store].path anchoring against config.rs.
/health's response shape, and that it is the only unauthenticated route, against web.rs.
Overlay contents and file count (24 = Bridge.cfg + Scripts.csproj + 22 Bridge scripts), the patch/companion-file table, and the boot + [bridge status console output against servuo-plugins/overlay/ and patches/README.md.
Admin �� Shard field labels against website/client/src/routes/admin/views/ShardAdmin.jsx.
Release asset names, SHA256SUMS presence and download URLs against the live v1.1.0 / v0.1.1 releases and bundles/current.json.

Appendix A's commands have not been executed end to end on a clean host — that live walk is the Phase 1 acceptance test the appendix is written to be.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Closes the last Phase 0 item of the installer plan: `docs/installer/INSTALL.md`, the operator-facing guide. It is written **before** the installer binary on purpose. Everything it installs is already released (0.1–0.3: the overlay tarball, the sidecar with `--print-config`, and the bundle manifest), so the guide is not speculation about a tool that might exist — it is the specification of what the run asks, where it writes, what it prints, and what the operator does next. Phases 1–4 implement it. **It is useful today.** 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. 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. Contents: what gets installed and what it deliberately does not do · prerequisites · download + checksum verification (the artifacts are unsigned, so this is the trust anchor) · the run, its prompts and its flag surface · where everything lands on both OSes · the opt-in patch tier and exactly what skipping it costs · the token handoff mapped onto the Admin → Shard fields · **how to verify the bridge actually works** rather than merely installed · `doctor`/`update`/`uninstall` · a troubleshooting table · appendices for `sidecar.toml` and the `Bridge.cfg` settings most shards want to review. ### Four things writing it settled (now recorded in `PLAN.md`) - **The installer does not install itself.** §5's `runicgateway doctor` sketch implied a name on `PATH`; nothing places one there. Day-two commands run from the downloaded binary. - **The flag surface.** `--servuo`, `--patches`/`--no-patches`, `--host`, `--site-url`, `--yes` join the `--verify`/`--bundle`/`--purge` the plan already named, so every prompt has a non-interactive equivalent and an unattended install is expressible. - **A modified `Config/Bridge.cfg` is reported, not overwritten** — one deliberate deviation from `deploy.ps1`. Its overwrite-on-hash-differs rule is right for a developer redeploying their own tree and wrong for an operator: an `update` would silently revert `LinkUrl`, `PublicConnectAddress`, sweep intervals — the shard's whole bridge configuration. `install.json`'s recorded hashes are what make "the operator edited this" distinguishable from "the overlay moved on". Every `.cs` file and `Scripts.csproj` still overwrite unconditionally. - **Remote-website deployments.** `[web] bind` defaults to loopback, which only works when the site runs on the shard host. Widen it, firewall it to the website's address, and front it with TLS or a VPN off a trusted network — the token is always required but travels as a plain bearer over HTTP. `[shard] bind` stays on loopback, because that socket carries inbound commands *into* the game. Also adds the missing `installer/` section to the docs index (it was never added when `PLAN.md` landed), and refreshes two stale examples in `PLAN.md` — the `doctor` sample's overlay file count (30 → 24, the real count) and sidecar version (0.3.0 → 1.1.0). ## How it was tested Documentation only — no code. Every value in the guide was checked against the source rather than written from memory: - CLI flags, `--print-config` JSON keys, `--version` output and the `UOLINK_*` environment overrides against `link/sidecar/src/{cli,config,main}.rs`; the bind/db defaults and the config-relative `[store].path` anchoring against `config.rs`. - `/health`'s response shape, and that it is the only unauthenticated route, against `web.rs`. - Overlay contents and file count (24 = `Bridge.cfg` + `Scripts.csproj` + 22 Bridge scripts), the patch/companion-file table, and the boot + `[bridge status` console output against `servuo-plugins/overlay/` and `patches/README.md`. - Admin �� Shard field labels against `website/client/src/routes/admin/views/ShardAdmin.jsx`. - Release asset names, `SHA256SUMS` presence and download URLs against the live `v1.1.0` / `v0.1.1` releases and `bundles/current.json`. Appendix A's commands have not been executed end to end on a clean host — that live walk is the Phase 1 acceptance test the appendix is written to be. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-04 16:39:49 +00:00

docs(installer): add the operator install guide (Phase 0.4) 5c8585fe75

Closes the last Phase 0 item. INSTALL.md is written before the installer
binary on purpose: everything it installs is already released (0.1-0.3), so
the guide is not speculation about a tool that might exist - it is the
specification of what the run asks, where it writes, what it prints, and what
the operator does next.

It is useful today. Appendix A is the same deployment done by hand - bundle
fetch, tarball verify and overlay copy, the optional patch tier,
--print-config provisioning, systemd unit / sc create - composed from the
released artifacts' actual contents and the sidecar's config and CLI source.
That appendix doubles as Phase 1's acceptance test.

Writing it settled four things the plan had left implicit, now recorded in
PLAN.md:

- The installer does not install itself; day-two commands run from the
  downloaded binary.
- The flag surface: --servuo, --patches/--no-patches, --host, --site-url and
  --yes join the --verify/--bundle/--purge the plan already named, so every
  prompt has a non-interactive equivalent.
- A modified Config/Bridge.cfg is reported, not overwritten - one deliberate
  deviation from deploy.ps1, whose overwrite-on-hash-differs rule is right for
  a developer and would silently revert an operator's whole shard config on
  update. install.json's recorded hashes are what make the distinction
  possible.
- Remote-website deployments: widen [web] bind, firewall it to the site's
  address, front it with TLS or a VPN off a trusted network. [shard] bind
  stays on loopback because that socket carries commands into the game.

Also adds the missing installer/ section to the docs index, and refreshes two
stale examples in PLAN.md (overlay file count, sidecar version).

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude added 1 commit 2026-08-04 16:40:27 +00:00

docs(installer): link the Phase 0.4 PR from the status table 83bd4ec2d4

whitlocktech approved these changes 2026-08-04 17:09:34 +00:00

whitlocktech merged commit e85ca632ce into main

2026-08-04 17:11:44 +00:00

whitlocktech referenced this issue from a commit

2026-08-04 17:11:45 +00:00

Merge pull request 'docs(installer): add the operator install guide (Phase 0.4)' (#87) from docs/installer-phase-0.4 into main

whitlocktech deleted branch docs/installer-phase-0.4

2026-08-04 17:11:50 +00:00

wtclaude referenced this pull request

2026-08-04 19:02:51 +00:00