# 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//` 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//.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.