Add reproducible headless desktop for the X11/NVENC capture path

A Moonlight client connecting to the x11-backend host got a black screen
even though pairing, NVENC, and input injection all worked: the headless
Xorg on :0 had no window manager rendering on it, so capture=x11 grabbed
an empty black root window. (The wlr/kms backends don't hit this — their
capture source renders for itself.)

This was a hand-built path with nothing in the repo to reproduce the
desktop piece. Now:

- files/headless-desktop.service: Openbox session on :0, bound to
  xorg-headless.service, enabled via default.target for lingering boots,
  with a best-effort xsetroot so the desktop is visibly non-black.
- lib/headless.sh: capture_backend_is_x11 + install_headless_desktop
  (idempotent; pulls openbox/xsetroot via the distro dispatch).
- install.sh: installs the desktop unit when capture=x11 is detected.
- status.sh: x11 branch now FAILs if no window manager is on :0 instead
  of only checking the X server answers — the gap that hid this failure.
- docs: TROUBLESHOOTING §13 black-screen lesson; FOLLOWUPS P3 updated.

Part of the P3 x11-backend work; --backend flag, config.sh x11 variant,
and xorg-headless templates remain outstanding.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-02 23:43:00 +00:00
parent ab23107300
commit 6fc34a2bd2
6 changed files with 137 additions and 0 deletions

View File

@@ -187,6 +187,16 @@ main() {
step "Installing headless prep-cmd hooks"
install_headless_hooks
fi
# X11/NVENC headless backend (capture = x11): the headless Xorg on :0 has
# no compositor of its own, so it needs a window manager rendering on it or
# Sunshine captures a black screen. Detected from the existing sunshine.conf
# (this backend is hand-configured; see FOLLOWUPS.md P3). Harmless no-op on
# the wlr/kms backends, whose capture source renders for itself.
if capture_backend_is_x11; then
step "Installing headless desktop (Openbox on :0 for the X11 capture path)"
install_headless_desktop
fi
# NOTE: the headless prestart drop-in needs the sunshine unit to already
# exist; install it after service-unit detection in enable_sunshine_service.