initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Quick Browser-Based Remote Desktop (x11vnc + noVNC)
+
+Lightweight alternative to Sunshine/Moonlight when you need to view the desktop in a laptop browser — no client install, no pairing, zero config beyond apt packages. Useful for quick admin tasks, one-off desktop viewing, or when Moonlight isn't available on the client.
+
+## When to use
+
+- View the desktop from a laptop browser (Chrome, Firefox, Safari)
+- No client software allowed/available on the remote machine
+- Quick one-off access — don't need persistent pairing or low-latency game streaming
+- User says "I need to see my desktop in my browser"
+
+## Setup (one-time)
+
+```bash
+sudo apt-get install -y x11vnc websockify novnc
+```
+
+## Launch (run each time)
+
+```bash
+# 1. Kill any stale processes from previous runs
+pkill x11vnc 2>/dev/null
+pkill websockify 2>/dev/null
+sleep 1
+
+# 2. Share the existing display via VNC (no password, shared)
+#    -noxdamage fixes black screen with noVNC
+#    -scale 1920x1080 downsamples 4K for browser performance
+x11vnc -display :0 -forever -shared -nopw -noxdamage -scale 1920x1080 &
+
+# 3. Use the official noVNC launcher (handles websockify bridge internally)
+/usr/share/novnc/utils/novnc_proxy --listen 6800 --vnc localhost:5900 --web /usr/share/novnc &
+```
+
+**IMPORTANT:** Using the official `novnc_proxy` launcher is preferred over raw `websockify`. It starts its own internal websockify, serves noVNC files, and handles the WebSocket handshake correctly. It serves `vnc.html` (the full noVNC client) at the root, not just `vnc_lite.html`.
+
+## Verify
+
+```bash
+# x11vnc listening (port 5900)
+ss -tlnp | grep 5900
+
+# novnc_proxy listening (port 6800, 0.0.0.0 = accessible from LAN)
+ss -tlnp | grep 6800
+
+# noVNC serving
+curl -s -o /dev/null -w "%{http_code}" http://localhost:6800/vnc.html
+# Expect: 200
+```
+
+## Client URL
+
+Open in laptop browser:
+
+```
+http://<server-ip>:6800/vnc.html
+```
+
+The `novnc_proxy` launcher auto-fills the WebSocket connection parameters — no query params needed. Example: `http://192.168.50.98:6800/vnc.html`
+
+## Teardown
+
+```bash
+pkill x11vnc
+pkill websockify
+pkill -f novnc_proxy
+```
+
+## Pitfalls
+
+- **UFW blocks port 6800 by default.** If the client browser says "site can't be reached," open the port: `sudo ufw allow 6800/tcp`.
+- **Black screen in noVNC.** If noVNC connects but shows only black (no desktop), first check whether it's a VNC encoding issue or the GPU framebuffer itself is black. Take an X11 screenshot to distinguish: `DISPLAY=:0 xwd -root -out /tmp/screen.xwd && convert /tmp/screen.xwd /tmp/screen.png`. If the screenshot is all-black (tiny file, ~1.3KB for any resolution), the GPU isn't rendering anything — check DRM connector state: `for c in /sys/class/drm/card*-HDMI-*/; do echo "$(basename $c): $(cat $c/enabled) dpms=$(cat $c/dpms)"; done`. If `enabled=disabled` and `dpms=Off`, the display is in a kernel-level DPMS lockup and only a reboot will fix it (see `references/debug-black-screen.md` for full workflow). If the screenshot shows the desktop but noVNC shows black, it's a VNC encoding issue — add `-noxdamage` to x11vnc. XDamage can fail to track on 4K displays and with compositing enabled.
+- **4K display kills browser performance.** Streaming a native 4K (3840x2160) framebuffer over noVNC is extremely heavy for the browser. Always downsample with `-scale 1920x1080` (or `-scale 1280x720` for slower connections). The x11vnc `-scale` flag handles this server-side.
+- **Use novnc_proxy, not raw websockify.** The Debian `novnc` package includes `/usr/share/novnc/utils/novnc_proxy` — a wrapper script that manages websockify internally, serves the full `vnc.html` client, and handles auto-connect better than the raw `websockify --web=...` command.
+- **websockify binds 0.0.0.0 by default** — accessible from LAN. No auth on this setup; only use on trusted networks.
+- **x11vnc -nopw means NO password.** Anyone on the LAN can connect to port 5900 directly. Acceptable for quick local use; don't leave running.
+- **Contrasts with Sunshine/Moonlight:** This is pure software encode (no NVENC), higher latency, higher CPU usage. Fine for desktop viewing; terrible for gaming.