installer
This commit is contained in:
118
rig/docs/notes/installer-testing.md
Normal file
118
rig/docs/notes/installer-testing.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Testing the installer
|
||||
|
||||
## Why it needs its own tiers
|
||||
|
||||
The installer is `ctrl/deps.sh`. What reaches a machine is its generated one-file kit,
|
||||
`standalone/default/rigdeps.sh`: the AWS Workspace gets that file and nothing else. The
|
||||
machines it must work on are exactly the ones you cannot rebuild to test on:
|
||||
- the Workspace cannot be recreated;
|
||||
- redoing WSL means rebuilding the machine you work on every day;
|
||||
- a fresh install happens once per machine, so a bug there is found by the one person least
|
||||
able to diagnose it.
|
||||
|
||||
So each tier is cheaper than the one after it, and each catches what the one before cannot.
|
||||
|
||||
| tier | runs | needs | proves | cannot prove |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 host fixtures | every `make selftest` | nothing | detection reads each kind of machine right: distro, WSL, memory, overcommit, systemd, `.wslconfig`, the Git Bash refusal | that anything installs |
|
||||
| 2 clean containers | `make selftest install` | docker, network, ~1–2 min | a stock Ubuntu 22.04 / Debian refuses cleanly when bare, then installs, verifies and fetches the manifests **as a non-root user**; the offline image works with no network | WSL, the Workspace's own policies, docker itself |
|
||||
| 3a Workspace snapshot | by hand, when the Workspace changes | the kit, once, on the Workspace | tier 1 replays the real Workspace's shape from then on | its install (that is tier 2's Ubuntu 22.04 plus the real run) |
|
||||
| 3b WSL throwaway | by hand, before teaching or after a WSL change | a Windows machine | the whole path in a real WSL distro that is not your daily one | Windows-side setup (not built, see below) |
|
||||
|
||||
## Tier 1 — host fixtures
|
||||
|
||||
`tests/hosts/<name>/` is a stand-in machine:
|
||||
|
||||
```
|
||||
root/ the files detect reads: etc/os-release, proc/version, proc/meminfo,
|
||||
proc/sys/vm/overcommit_memory, etc/wsl.conf, mnt/c/Users/<u>/.wslconfig
|
||||
env optional KEY=value lines, e.g. UNAME_S=MINGW64_NT-10.0 (a fact no file carries)
|
||||
expect.txt "+ text" must appear, "- text" must not, "exit N" (default 0)
|
||||
```
|
||||
|
||||
`bash ctrl/hosttest.sh [DIR...]` runs `deps.sh detect all` with `HOST_ROOT` pointing at the
|
||||
root (which also sets `MEMINFO` and `OVERCOMMIT_FILE`) and checks the lines. Only host facts are
|
||||
asserted: docker, PATH and the filesystem belong to the machine running the test.
|
||||
|
||||
Shipped: `ubuntu-22.04` (the Workspace's shape: 7.6 GB, overcommit 1, swap in use),
|
||||
`debian-trixie`, `wsl-bare` (systemd off, no `.wslconfig`), `wsl-ready`, `git-bash`. To add a
|
||||
case, add a folder. Anything true of one real machine goes with an overlay or in `local/`,
|
||||
never here.
|
||||
|
||||
## Tier 2 — clean containers
|
||||
|
||||
`make selftest install` (`ctrl/installtest.sh [IMAGE...]`). It first refuses to run on a stale
|
||||
kit, then, for `ubuntu:22.04` and `debian:trixie-slim`:
|
||||
1. **bare:** `install` must refuse and name curl/wget — the bootstrap paradox;
|
||||
2. **after the one root step** (`apt-get install curl ca-certificates`), as a plain user:
|
||||
`install dev`, `verify dev`, `manifests --to ~/m`. The dev tier lands in `~/.local/bin`,
|
||||
the PATH advice is printed, and all three manifests are there, verified.
|
||||
|
||||
Then it builds `deps-full` and runs `install` + `manifests` with `--network none`: the
|
||||
air-gapped path. Measured 2026-09-22: 15 checks, 75 s.
|
||||
|
||||
## Tier 3a — the Workspace snapshot
|
||||
|
||||
```bash
|
||||
bash rigdeps.sh snapshot ~/rig-host-snapshot # on the Workspace; the kit is enough
|
||||
```
|
||||
|
||||
It writes the files detect reads, cut down to what detect needs:
|
||||
- the `os-release` name fields;
|
||||
- the kernel release;
|
||||
- four meminfo numbers;
|
||||
- the overcommit value;
|
||||
- `wsl.conf`'s section headers and its two keys;
|
||||
- a `.wslconfig` memory line, under the neutral user `user`;
|
||||
- `facts.txt` (arch, glibc, date);
|
||||
- `expect.txt`, the lines detect printed for it.
|
||||
|
||||
No environment, no home, no host name: selftest asserts both the file list and the absence
|
||||
of those.
|
||||
|
||||
Carry the folder back, keep it in `local/hosts/workspace/` (gitignored) or with the overlay,
|
||||
and from then on:
|
||||
|
||||
```bash
|
||||
bash ctrl/hosttest.sh local/hosts/workspace
|
||||
```
|
||||
|
||||
Add your own `+`/`-` lines to its `expect.txt` for what must stay true there. Take a new one
|
||||
when the Workspace changes (an image update, a memory change).
|
||||
|
||||
## Tier 3b — WSL, in a throwaway distro
|
||||
|
||||
Never the distro you work in: a second one, imported from a rootfs, removed afterwards. WSL
|
||||
runs every distro in one VM, so this changes nothing in yours — **except that
|
||||
`wsl --shutdown` stops both**; don't run it while you work. From PowerShell:
|
||||
|
||||
```powershell
|
||||
# a pristine Ubuntu 22.04 rootfs: from cloud-images.ubuntu.com/wsl/, or
|
||||
# `wsl --export Ubuntu-22.04 ubuntu-22.04.tar` of an untouched install kept for this
|
||||
wsl --import rig-test C:\wsl\rig-test .\ubuntu-22.04.tar
|
||||
wsl -d rig-test -u root -- bash -c "apt-get update && apt-get install -y curl ca-certificates && useradd -m t"
|
||||
copy .\rigdeps.sh \\wsl$\rig-test\home\t\
|
||||
wsl -d rig-test -u t -- bash -lc "cd ~ && bash rigdeps.sh detect all && bash rigdeps.sh install dev && bash rigdeps.sh verify dev && bash rigdeps.sh snapshot ~/snap"
|
||||
# carry \\wsl$\rig-test\home\t\snap back as a fixture, then:
|
||||
wsl --unregister rig-test
|
||||
```
|
||||
|
||||
What to look for: detect says `WSL`, and names the systemd and `.wslconfig` steps; install and
|
||||
verify pass. This is the tier to run before teaching Windows users, or after a WSL update.
|
||||
Nothing in rig automates it: a throwaway-distro harness is the multi-distro machinery that
|
||||
was removed on purpose.
|
||||
|
||||
## Not built: a Windows-host installer
|
||||
|
||||
Everything above starts inside Linux. The Windows side — enabling WSL, getting a distro, and
|
||||
the tools a Windows user needs before rig (python and the like) — is still manual, in the
|
||||
README's "Starting from plain Windows". A Windows-host installer is recorded for the future,
|
||||
for teaching; it would need tier 3b's approach, a machine that is not your daily one, to test.
|
||||
|
||||
## The hooks the tiers rely on
|
||||
|
||||
`deps.sh` reads host files through `HOST_ROOT` (`host_file()`), memory through `MEMINFO`, the
|
||||
overcommit mode through `OVERCOMMIT_FILE`, the kernel name through `UNAME_S`, and WSL through
|
||||
`host_file /proc/version`. With `HOST_ROOT` set, `MEMINFO` and `OVERCOMMIT_FILE` default into
|
||||
it. The deps image relies on `HOST_ROOT=/host` for the same reason: a container asking about
|
||||
its host.
|
||||
Reference in New Issue
Block a user