docs(installer): record Phase 2 as built — sidecar install and service #91

wtclaude · 2026-08-04T20:41:38Z

wtclaude commented

2026-08-04 20:41:38 +00:00

What & why

Docs half of installer#5 — Phase 2 of installer/PLAN.md is built and on the installer repo's edge branch, so the design of record and the operator guide move with it.

PLAN.md

Status: phases 1 and 2 built. The edge → main cutover now follows Phase 3, not Phase 2 — INSTALL.md §4 describes the patch tier as part of the run, and a first release that answers "not implemented" to all of it is the same half-capable binary that kept Phase 1 off main.
§2.3 corrected: the service definition always pins the config path, but only Linux pins the database. On Windows config and data share a directory, so the sidecar's own anchoring rule already lands it correctly — and sc.exe offers no per-service environment, only a machine-wide one that every process on the host inherits and that outlives an uninstall.
New "Phase 2 as built": the virtual service account, the config lockdown and why its two halves straddle registration, --verify running no part of the sidecar half, the protocol check against the installed binary, RUNICGATEWAY_STATE_DIR relocating the binary and suppressing service registration, degrading to a printed recipe with no root/LocalSystem fallback, and the token never entering install.json.
§8 question 1 resolved (Windows service mechanism): sc create, as recommended — plus the service identity the recommendation did not anticipate.

INSTALL.md

Status banner: what is built, and that the patch tier is the remaining gap.
§2: the illustrated run matches the sidecar block the binary actually prints.
§3: a table of how each platform pins config and database, the dedicated service account on both, and the fact that sidecar.toml's permissions are restricted because it holds the auth token.
Appendix A4 rewritten for Windows so the hand install matches what the installer does: --config in binPath (single-quoted, so PowerShell keeps the inner quotes the SCM needs), obj= for the virtual account, the icacls lockdown before and the grants after, and no machine-wide environment variables.
Troubleshooting: a row for a run that could not register a service, and one for a service that starts and immediately stops.

How it was tested

Prose only. Every claim added here was checked against the code it describes, and the behaviour it documents was exercised end to end on Windows — see the testing section of installer#5.

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)

AI tools were used. Tool(s): Claude Code. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-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 Docs half of [installer#5](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/5) — Phase 2 of [`installer/PLAN.md`](PLAN.md) is built and on the installer repo's `edge` branch, so the design of record and the operator guide move with it. ### PLAN.md - **Status**: phases 1 and 2 built. The `edge → main` cutover now follows **Phase 3**, not Phase 2 — `INSTALL.md` §4 describes the patch tier as part of the run, and a first release that answers "not implemented" to all of it is the same half-capable binary that kept Phase 1 off `main`. - **§2.3** corrected: the service definition always pins the *config* path, but only Linux pins the database. On Windows config and data share a directory, so the sidecar's own anchoring rule already lands it correctly — and `sc.exe` offers no per-service environment, only a machine-wide one that every process on the host inherits and that outlives an uninstall. - **New "Phase 2 as built"**: the virtual service account, the config lockdown and why its two halves straddle registration, `--verify` running no part of the sidecar half, the protocol check against the installed binary, `RUNICGATEWAY_STATE_DIR` relocating the binary and suppressing service registration, degrading to a printed recipe with no root/LocalSystem fallback, and the token never entering `install.json`. - **§8 question 1 resolved** (Windows service mechanism): `sc create`, as recommended — plus the service identity the recommendation did not anticipate. ### INSTALL.md - Status banner: what is built, and that the patch tier is the remaining gap. - §2: the illustrated run matches the sidecar block the binary actually prints. - §3: a table of how each platform pins config and database, the dedicated service account on both, and the fact that `sidecar.toml`'s permissions are restricted because it holds the auth token. - **Appendix A4 rewritten for Windows** so the hand install matches what the installer does: `--config` in `binPath` (single-quoted, so PowerShell keeps the inner quotes the SCM needs), `obj=` for the virtual account, the `icacls` lockdown before and the grants after, and no machine-wide environment variables. - Troubleshooting: a row for a run that could not register a service, and one for a service that starts and immediately stops. ## How it was tested Prose only. Every claim added here was checked against the code it describes, and the behaviour it documents was exercised end to end on Windows — see the testing section of installer#5. ## 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) - [x] AI tools were used. Tool(s): `Claude Code`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-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 20:41:40 +00:00

docs(installer): record Phase 2 as built — sidecar install and service 3f12e5f49c

Phases 1 and 2 now live on the installer repo's `edge` branch, so PLAN.md's
status, the config-path section, and the operator guide all move with them.

PLAN.md
- Status: phases 1 and 2 built. The `edge -> main` cutover now follows Phase 3
  rather than Phase 2, because INSTALL.md §4 describes the patch tier as part of
  the run and a release that answers "not implemented" to all of it is the same
  half-capable binary that kept Phase 1 off `main`.
- §2.3: the service definition always pins the config path, but only Linux pins
  the database. On Windows config and data share a directory, so the sidecar's
  own anchoring rule already lands it correctly — and `sc.exe` offers no
  per-service environment, only a machine-wide one that every process inherits
  and that outlives an uninstall.
- New "Phase 2 as built" section: the virtual service account, the config
  lockdown and why its two halves straddle registration, `--verify` running no
  part of the sidecar half, the protocol check against the installed binary,
  `RUNICGATEWAY_STATE_DIR` relocating the binary and suppressing service
  registration, degrading to a printed recipe with no root/LocalSystem fallback,
  and the token never entering install.json.
- §8 question 1 (Windows service mechanism) resolved: `sc create`, as
  recommended — plus the service identity the recommendation did not anticipate.

INSTALL.md
- Status banner: what is built, and that the patch tier is the remaining gap.
- §2: the illustrated run matches the sidecar block the binary actually prints.
- §3: a table of how each platform pins config and database, the dedicated
  service account on both, and the fact that sidecar.toml's permissions are
  restricted because it holds the auth token.
- Appendix A4: the Windows recipe now matches what the installer does —
  `--config` in binPath (single-quoted so PowerShell keeps the inner quotes),
  `obj=` for the virtual account, the icacls lockdown before and grants after,
  and no machine-wide environment variables.
- Troubleshooting: a row for a run that could not register a service, and one
  for a service that starts and immediately stops.

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

wtclaude referenced this pull request from RunicGateway/installer

2026-08-04 20:42:18 +00:00

feat(installer): implement Phase 2 — uo-link install and service #5

whitlocktech approved these changes 2026-08-04 20:44:52 +00:00

whitlocktech merged commit 5ae53d287f into main

2026-08-04 20:45:04 +00:00

whitlocktech deleted branch docs/installer-phase2

2026-08-04 20:45:04 +00:00

whitlocktech referenced this issue from a commit

2026-08-04 20:45:07 +00:00

Merge pull request 'docs(installer): record Phase 2 as built — sidecar install and service' (#91) from docs/installer-phase2 into main

Sign in to join this conversation.