119 lines
6.1 KiB
Markdown
119 lines
6.1 KiB
Markdown
# 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.
|