diff --git a/docs/RUNBOOK-PhaseC.md b/docs/RUNBOOK-PhaseC.md index 547b0dc..ff96f2f 100644 --- a/docs/RUNBOOK-PhaseC.md +++ b/docs/RUNBOOK-PhaseC.md @@ -216,24 +216,29 @@ ci vm cleanup --max-age-hours 4 --lock-file /var/lib/ci/vm-start.lock Launches the **interactive** VMware Workstation GUI (not the headless vmrun path) so you can watch/poke a clone by hand. -**Required once per desktop session** — authorise `ci-runner` on your X server -(run as YOUR logged-in user, not ci-runner): +On a normal desktop session it just works — `sudo` already forwards `DISPLAY`, +and `vmgui` behaves exactly like `sudo -u ci-runner vmware`: +```bash +ci vmgui # bare GUI, no VM +ci vmgui --vmx /var/lib/ci/build-vms/Clone_dbg-1_*/Clone_dbg-1_*.vmx +ci vmgui --vmx --power-on # power it on (-x) +ci vmgui --vmx --fullscreen # power on + fullscreen (-X) +``` +Other flags: `--new-window` (`-n`), `--display :0` (force a display if `$DISPLAY` +isn't forwarded), `--vmware-path`. Spawns detached; prints PID + log path. + +**Why it works**: VMware connects via the X **host ACL**, not the cookie. The +inherited `XAUTHORITY` (the desktop user's `~/.Xauthority`) is unreadable by +ci-runner, so `vmgui` drops it and relies on the xhost grant — which is normally +already present (`xhost` lists `SI:localuser:ci-runner`). + +**Only if you get `cannot open X display`**: the grant is missing. Add it from +the logged-in desktop user (not ci-runner): ```bash xhost +SI:localuser:ci-runner ``` -Then open the GUI as ci-runner, forcing the display: -```bash -ci vmgui --vmx /var/lib/ci/build-vms/Clone_dbg-1_*/Clone_dbg-1_*.vmx --display :0 -ci vmgui --vmx --display :0 --power-on # also power it on (-x) -ci vmgui --vmx --display :0 --fullscreen # power on + fullscreen (-X) -ci vmgui --display :0 # bare GUI, no VM loaded -``` -**If nothing opens**: you skipped the `xhost` step. `vmgui` now pre-flights the -display (`xdpyinfo`) and fails with the exact `xhost` command instead of dying -silently; it also drops an unreadable inherited `XAUTHORITY` and logs the GUI's -output to `/tmp/vmgui-*.log`. The GUI needs an X display — `sudo -u ci-runner` -loses your cookie, so `xhost` + `--display :0` is the reliable combo. Other -flags: `--new-window` (`-n`), `--vmware-path`. Spawns detached, prints PID + log. +`vmgui` pre-flights the display (`xdpyinfo`) and prints this exact command on +failure instead of dying silently; the GUI's output is captured in `/tmp/vmgui-*.log`. ---