docs(readme): describe the tool that exists, not Phase 1
All checks were successful
PR Checks / rust-gates (pull_request) Successful in 1m0s
All checks were successful
PR Checks / rust-gates (pull_request) Successful in 1m0s
PLAN.md §5.4. The status section still announced Phase 1 as built and Phase 2 as next, four phases later -- it is the first thing a visitor to this repo reads, and it has been wrong since Phase 2 merged. - The phase table now shows 1-4 built on `edge` and 5 in progress, and the opening says what the binary actually does. - "What the cutover is waiting on" is stated, because "nothing is released yet" invites the question: Phase 5, and the Windows SCM half never having been executed anywhere. - "Planned commands" is now "Commands". All four are implemented. - RUNICGATEWAY_STATE_DIR was described as relocating install.json. Since Phase 2 it relocates everything the installer writes, including the sidecar binary, and suppresses service registration -- an out-of-date description of where a tool writes is worse than none. - A design-constraint bullet for the backup behaviour Phase 5 adds. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
50
README.md
50
README.md
@@ -27,7 +27,13 @@ never restarts the shard.
|
||||
|
||||
## Status
|
||||
|
||||
**Phase 1 (installer core) is built, on the `edge` branch. Nothing is released yet.**
|
||||
**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)
|
||||
@@ -42,17 +48,29 @@ sidecar + overlay combination, recomposed on every component release and nightly
|
||||
|---|---|
|
||||
| 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 | next |
|
||||
| 3 — the opt-in stock-file patch tier | |
|
||||
| 4 — `doctor`, `update`, `uninstall` | |
|
||||
| 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`, and a binary that deploys the overlay but cannot yet install the sidecar
|
||||
is not something to hand an operator. Phases 1 and 2 land on `edge`; the
|
||||
`edge → main` cutover cuts the first release. PRs into `edge` run the same gates
|
||||
as PRs into `main`.
|
||||
`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`.
|
||||
|
||||
Until then, the way to install is by hand —
|
||||
**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`.
|
||||
|
||||
@@ -66,7 +84,7 @@ is the same deployment done with `curl`, `tar` and `systemctl`.
|
||||
| [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. |
|
||||
|
||||
## Planned commands
|
||||
## Commands
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
@@ -90,6 +108,10 @@ is the same deployment done with `curl`, `tar` and `systemctl`.
|
||||
- **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
|
||||
@@ -103,8 +125,12 @@ cargo run -- install --servuo /path/to/ServUO --verify # dry run: writes nothi
|
||||
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
|
||||
```
|
||||
|
||||
`RUNICGATEWAY_STATE_DIR` relocates `install.json` (normally `/etc/runicgateway`
|
||||
or `%ProgramData%\RunicGateway`), which is how a run is tested without root.
|
||||
`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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user