From 060ac6c078a37e5b3ed563a5fce1900ffb179c63 Mon Sep 17 00:00:00 2001
From: Samuel James <143277412+SamuelSJames@users.noreply.github.com>
Date: Mon, 22 Jun 2026 14:50:55 -0400
Subject: [PATCH] Document xrdp blank-screen fix (Wayland-only GNOME needs
 XFCE) (#42)

After replacing gnome-remote-desktop with xrdp, the connection succeeded but
showed a blank screen: GNOME 50 on Fedora is Wayland-only and can't run on
xrdp's Xorg backend, so the session started and died in ~2s. Fixed by installing
XFCE (an X11 desktop that works without GL) and creating the missing
/etc/xrdp/startwm.sh to launch it. Verified xfce4-session/xfwm4 persist and
guacd streams sustained desktop frames.

Co-authored-by: Samuel James <ssamjame@amazon.com>
Co-authored-by: Kiro <noreply@kiro.dev>
---
 docs/rdp-debug-handoff.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/rdp-debug-handoff.md b/docs/rdp-debug-handoff.md
index 2845a07..03d04e8 100644
--- a/docs/rdp-debug-handoff.md
+++ b/docs/rdp-debug-handoff.md
@@ -38,6 +38,26 @@ plus the alternative considered:
   streams live desktop frames. **`security` MUST be `any` (or blank → defaults to `any`)** for
   xrdp's default config — `nla` fails (`Security negotiation failed`) and `rdp` errors out.
   Note: xrdp gives a fresh X login session, not a takeover of the existing Wayland session.
+
+  **Gotcha (connected-but-blank screen):** after installing xrdp you may connect successfully
+  but see a blank/black screen. Cause: **GNOME 50 on Fedora is Wayland-only** (no Xorg session
+  in `/usr/share/xsessions/`), so it cannot run on xrdp's Xorg backend — the session starts and
+  dies in ~2s (`xrdp-sesman` logs `Session on display N has finished`). Fix: install a
+  lightweight **X11** desktop and point xrdp at it:
+  ```bash
+  sudo dnf install -y @xfce-desktop      # XFCE: X11, no GL needed, reliable over xrdp
+  # /etc/xrdp/startwm.sh was missing on this VM — create it:
+  sudo tee /etc/xrdp/startwm.sh >/dev/null <<'WM'
+  #!/bin/sh
+  [ -r /etc/profile ] && . /etc/profile
+  export XDG_SESSION_TYPE=x11
+  export XDG_CURRENT_DESKTOP=XFCE
+  exec startxfce4
+  WM
+  sudo chmod +x /etc/xrdp/startwm.sh
+  sudo systemctl restart xrdp-sesman xrdp
+  ```
+  Verified: `xfce4-session` + `xfwm4` stay running and guacd streams sustained desktop frames.
 - **Alternative (infra, affects everyone): a custom guacd build with FreeRDP 3.** Not worth it
   yet — it's a 30+ min from-source build to maintain in `docker-compose.yml`, for one upstream
   gap that Apache will eventually close. Revisit if/when `guacamole/guacd` ships FreeRDP 3.