Skip to content
gunkslab

Project

Install checklist

Run before every release, on a fresh machine for each platform below: a new virtual machine, or a new user account with nothing from gunkslab on it. It checks what a stranger meets, from an empty machine to driving a simulated bot, using only the docs. Each run’s result goes in the table at the end, and anything that went wrong goes on Known issues.

The platforms

# Platform Runtime Run the commands in
A macOS 26 or later, Apple silicon Apple’s container Terminal
B macOS 26 or later, Apple silicon Docker Desktop (RUNTIME=docker if container is also there) Terminal
C Windows 11 Docker Desktop, WSL2 integration on a WSL2 Ubuntu shell, the repo cloned inside WSL (~/), not on C:
D Ubuntu LTS docker, or podman a terminal
E Red Hat family (RHEL, Fedora, Rocky or Alma) podman a terminal

The steps

Write down the OS version and the runtime’s version first. Start a timer at step 2: the target is 15 minutes from step 2 to step 6.

  1. The runtime. Install it as Install says, and nothing else. Anything the page doesn’t say, but you had to do, is a finding.

  2. The repo. git clone it and cd gunkslab, as Install says.

  3. The check. scripts/check-protocol prints 15 schemas, all examples as expected.

  4. The doctor. ./gunkslab doctor ends nothing to fix, and its first check names the runtime you meant to use.

  5. Up. ./gunkslab up ends gunkslab: up, 2 simulated bots. and the page opens in the browser. On a platform that can’t open one (the doctor says so), it prints the address: open it yourself.

  6. Drive. On the page:

    • two bots, sim-1 and sim-2, on the desk;
    • pick sim-1 in the drive panel: the arrow keys and the on-screen pad move it;
    • click a spot on the desk: the bot drives there itself;
    • the e-stop stops both, and clearing it lets them move again.

    Stop the timer.

  7. Status, logs, version.

    • ./gunkslab status: four ok lines and the page’s address;
    • ./gunkslab logs: four files in logs/;
    • ./gunkslab version: the version being released.
  8. Recover.

    • scripts/station crash, then ./gunkslab doctor: FIX not running: station;
    • ./gunkslab down && ./gunkslab up: up again;
    • the doctor: nothing to fix.
  9. Down. ./gunkslab down, then ./gunkslab doctor: nothing running and nothing to fix.

  10. The tutorials’ start. Tutorial 01’s and 03’s commands work as written. A stranger runs tutorial 03 unaided for G1; this step only checks the commands.

A run passes when every step does, as written, within the 15 minutes. Anything else is a finding: put the step, what you saw and what fixed it on Known issues, and in an issue.

The runs

Date Version # OS and runtime, with versions Fresh? Steps 2–6 Result Findings
2026-10-25 0.1.0-dev B macOS 27.0.1, Docker Desktop with Docker Engine 20.10.7 no: a dev machine, images partly cached 36 s to step 5 steps 3–5 and 7–9 pass; 6 not run (needs a person at the page) none
2026-10-25 0.1.0-dev D Ubuntu 24.04.5 LTS, Docker 28.4.0 gunkslab’s part: no clone or images before; the runtime was there; the repo from a git bundle (it’s private) 14 s to step 5 steps 3–10 pass: 6 with the page in a Mac’s browser, through an SSH tunnel; 6 and 10 later the same day, on main at 89cf790 one, not a fault: a go-to boxed into a corner ends blocked, as tutorial 07 says; backing out of a dead end comes after G1
2026-10-25 0.1.0-dev E Rocky Linux 9.8, podman 5.8.2 (through its docker command), SELinux enforcing as D 28 s to step 5, after the fixes first run: 3 and 5 failed, SELinux refusing the containers the repo’s files; 4 called a taken port free (no nc). After the fixes: 3–5 and 7–10 pass (10 later the same day, on main at 89cf790); 6 not run three, fixed: mounts take z under SELinux; the port check uses ss or lsof without nc; up checks each piece is still running
2026-11-11 0.1.0-dev A macOS 27.0.1, Apple’s container 0.11.0 no: a dev machine; gunkslab’s images removed first, the build cache kept 12 s to step 5 all ten pass, at e65d34f (main with tutorial 03’s new order); 6 by a script driving the page in a headless Chrome, not a person none
2026-11-11 0.1.0-dev B macOS 27.0.1, Docker Desktop with Docker Engine 20.10.7 no: a dev machine, two of gunkslab’s images cached 29 s to step 5 all ten pass, at e65d34f; 6 as A none
2026-11-11 0.1.0-dev D Ubuntu 24.04.5 LTS, Docker 28.4.0 gunkslab’s part: no clone or images before; the runtime was there; the repo from a git bundle 16 s to step 5 all ten pass, at e65d34f; 6 as A, with the page in a Mac’s browser through an SSH tunnel one: over SSH, with no screen, the doctor said a browser can be opened (fixed the same day: it now says there’s no screen)
2026-11-11 0.1.0-dev E Rocky Linux 9.8, podman 5.8.2 (through its docker command), SELinux enforcing as D 29 s to step 5 all ten pass, at e65d34f; 6 as A, the browser in a Playwright container on the same machine (its SSH allows no tunnels) none
2026-11-11 0.1.0-dev C none none none not run: no Windows 11 machine to hand; 0.1.0 will ship with Windows listed as not tried yet none
2026-11-14 0.1.0-dev A macOS 27.0.1, Apple’s container 0.11.0 no: a dev machine; gunkslab’s images removed first, the build cache kept 60 s for steps 2–6 all ten pass, at 9393e11 (main after the move to the new project); 6 by a script driving the page in a headless Chrome, not a person none
2026-11-14 0.1.0-dev B macOS 27.0.1, Docker Desktop with Docker Engine 20.10.7 no: a dev machine; gunkslab’s images removed first 68 s for steps 2–6 all ten pass, at 9393e11; 6 as A none
2026-11-14 0.1.0-dev D Ubuntu 24.04.5 LTS, Docker 28.4.0 gunkslab’s part: no clone or images before; the runtime was there; the repo from a git bundle 59 s for steps 2–6 all ten pass, at 9393e11; 6 as A, with the page in a Mac’s browser through an SSH tunnel none
2026-11-14 0.1.0-dev E Rocky Linux 9.8, podman 5.8.2 (through its docker command), SELinux enforcing as D 52 s for steps 2–6 all ten pass, at 9393e11; 6 as A, the browser in a Playwright container on the same machine none
2026-11-14 0.1.0-dev C none none none not run: still no Windows 11 machine to hand; 0.1.0 ships with Windows listed as not tried yet none