Simone/local-ci-cd-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(vmgui): clarify it works like sudo -u ci-runner vmware

Browse Source 
The GUI connects via the X host ACL (xhost), not the inherited XAUTHORITY
cookie (unreadable by ci-runner). On a normal session the grant is already
present and `ci vmgui` works with no --display/xhost dance — sudo forwards
DISPLAY. xhost is only needed if you hit "cannot open X display". Drop the
overstated "--display :0 required" framing from §4.7.
This commit is contained in:
Simone
2026-06-08 00:30:21 +02:00
parent 23b5858802
commit b74e854d48
1 changed files with 20 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/RUNBOOK-PhaseC.md
+20 -15
View File
@@ -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 <path> --power-on # power it on (-x)
ci vmgui --vmx <path> --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 <path> --display :0 --power-on # also power it on (-x)
ci vmgui --vmx <path> --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`.
---