Tooling: Add VNC mode for easy Linux running

vdavid · vdavid · commit 6aa5ff7ce530 · 2026-02-09T22:23:57.000+01:00
- It runs the app in a VNC thing in a browser on a port. It's a bit weird, the VM feels better, but this is a small change so keeping it.
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
@@ -25,6 +25,7 @@
         "test:e2e:linux:native": "wdio run test/e2e-linux/wdio.conf.ts",
         "test:e2e:linux:build": "docker build -t cmdr-e2e -f test/e2e-linux/docker/Dockerfile test/e2e-linux/docker",
         "test:e2e:linux:shell": "./scripts/e2e-linux.sh --shell",
+        "test:e2e:linux:vnc": "./scripts/e2e-linux.sh --vnc",
         "knip": "knip",
         "check:type-drift": "tsx scripts/check-type-drift.ts"
     },
diff --git a/apps/desktop/scripts/e2e-linux.sh b/apps/desktop/scripts/e2e-linux.sh
@@ -8,6 +8,7 @@
 #   ./scripts/e2e-linux.sh           # Run tests
 #   ./scripts/e2e-linux.sh --build   # Force rebuild Docker image
 #   ./scripts/e2e-linux.sh --shell   # Start interactive shell in container
+#   ./scripts/e2e-linux.sh --vnc     # Interactive VNC mode with hot reload
 #   ./scripts/e2e-linux.sh --clean   # Clean Linux build cache
 
 set -e
@@ -46,6 +47,7 @@ log_error() {
 # Parse arguments
 FORCE_BUILD=false
 INTERACTIVE=false
+VNC_MODE=false
 CLEAN=false
 
 for arg in "$@"; do
@@ -56,6 +58,9 @@ for arg in "$@"; do
         --shell)
             INTERACTIVE=true
             ;;
+        --vnc)
+            VNC_MODE=true
+            ;;
         --clean)
             CLEAN=true
             ;;
@@ -65,6 +70,7 @@ for arg in "$@"; do
             echo "Options:"
             echo "  --build    Force rebuild of Docker image"
             echo "  --shell    Start interactive shell in container"
+            echo "  --vnc      Interactive VNC mode with hot reload (pnpm dev)"
             echo "  --clean    Clean Linux build cache (forces rebuild)"
             echo "  --help     Show this help message"
             exit 0
@@ -95,6 +101,65 @@ if $FORCE_BUILD || ! docker image inspect "$IMAGE_NAME" &> /dev/null; then
     docker build -t "$IMAGE_NAME" -f "$DESKTOP_DIR/test/e2e-linux/docker/Dockerfile" "$DESKTOP_DIR/test/e2e-linux/docker"
 fi
 
+# VNC mode: runs pnpm dev inside Docker with VNC for interactive debugging.
+# Does NOT require a pre-built binary — uses Vite + Tauri hot reload instead.
+if $VNC_MODE; then
+    log_info "Starting VNC mode with hot reload..."
+
+    # Temporarily clear .cargo/config.toml if present (local path patches don't exist in Docker)
+    CARGO_CONFIG="$DESKTOP_DIR/src-tauri/.cargo/config.toml"
+    CARGO_CONFIG_BAK=""
+    if [ -f "$CARGO_CONFIG" ]; then
+        CARGO_CONFIG_BAK="${CARGO_CONFIG}.docker-bak"
+        cp "$CARGO_CONFIG" "$CARGO_CONFIG_BAK"
+        > "$CARGO_CONFIG"
+        trap 'mv "${CARGO_CONFIG_BAK}" "${CARGO_CONFIG}" 2>/dev/null || true' EXIT
+    fi
+
+    docker run -it --rm \
+        -v "$REPO_ROOT:/app" \
+        -v "$CARGO_VOLUME:/root/.cargo" \
+        -v "$TARGET_VOLUME:/target" \
+        -v "$ROOT_NODE_MODULES_VOLUME:/app/node_modules" \
+        -v "$DESKTOP_NODE_MODULES_VOLUME:/app/apps/desktop/node_modules" \
+        -w /app \
+        -p 5990:5990 \
+        -p 6090:6090 \
+        -e VNC=1 \
+        -e CARGO_TARGET_DIR=/target \
+        -e TAURI_DEV_HOST=0.0.0.0 \
+        -e RUST_LOG=smb=warn,sspi=warn,info \
+        "$IMAGE_NAME" \
+        bash -c '
+            set -e
+
+            # Install dev packages needed for Tauri build
+            apt-get update > /dev/null && apt-get install -y \
+                libwebkit2gtk-4.1-dev \
+                libayatana-appindicator3-dev \
+                librsvg2-dev \
+                libacl1-dev \
+                patchelf \
+                > /dev/null
+
+            # Install dependencies if needed (node_modules is a Docker volume)
+            if [ ! -f "/app/node_modules/.linux-installed" ]; then
+                echo "Installing Linux node_modules..."
+                pnpm install --frozen-lockfile
+                touch /app/node_modules/.linux-installed
+            fi
+
+            echo "Starting Cmdr in dev mode (Vite HMR + Tauri)..."
+            echo "Frontend edits on macOS will hot reload in ~1-3s."
+            echo "Rust edits require Ctrl+C and re-run."
+            echo ""
+            pnpm dev
+        '
+
+    log_info "VNC session ended."
+    exit 0
+fi
+
 # Check if a Linux binary exists in the Docker volume
 # Override entrypoint to avoid Xvfb output
 check_linux_build() {
diff --git a/apps/desktop/test/e2e-linux/docker/Dockerfile b/apps/desktop/test/e2e-linux/docker/Dockerfile
@@ -42,6 +42,10 @@ RUN apt-get update && apt-get install -y \
     libcairo2 \
     libatk1.0-0 \
     libgdk-pixbuf-2.0-0 \
+    # VNC for interactive debugging (--vnc mode)
+    x11vnc \
+    novnc \
+    python3-websockify \
     # Useful utilities
     ca-certificates \
     # Clean up
diff --git a/apps/desktop/test/e2e-linux/docker/entrypoint.sh b/apps/desktop/test/e2e-linux/docker/entrypoint.sh
@@ -39,8 +39,21 @@ if ! kill -0 $XVFB_PID 2>/dev/null; then
 fi
 echo "Xvfb is running (PID: $XVFB_PID)"
 
-# Change to the app directory if we're mounted
-if [ -d "/app/apps/desktop" ]; then
+# Start VNC server if requested (for interactive debugging with --vnc mode)
+if [ "${VNC:-}" = "1" ]; then
+    echo "Starting VNC server..."
+    x11vnc -display :99 -forever -nopw -shared -rfbport 5990 -q &
+    /usr/share/novnc/utils/novnc_proxy --vnc localhost:5990 --listen 6090 &>/dev/null &
+    echo ""
+    echo "╔═══════════════════════════════════════════════════════════════════╗"
+    echo "║  Open in browser: http://localhost:6090/vnc.html?autoconnect=true  ║"
+    echo "║  Native VNC:      vnc://localhost:5990 (no password)               ║"
+    echo "╚═══════════════════════════════════════════════════════════════════╝"
+    echo ""
+fi
+
+# Change to the app directory if we're mounted (skip in VNC mode — it runs from repo root)
+if [ -d "/app/apps/desktop" ] && [ "${VNC:-}" != "1" ]; then
     cd /app/apps/desktop
 fi
 
diff --git a/docs/tooling/e2e-testing-guide.md b/docs/tooling/e2e-testing-guide.md
@@ -84,15 +84,15 @@ pnpm test:e2e:linux:native
 
 ## Test files
 
-| File                                  | Description                                    |
-|---------------------------------------|------------------------------------------------|
-| `test/e2e-smoke/smoke.test.ts`        | Playwright tests for basic UI (browser-based)  |
-| `test/e2e-linux/app.spec.ts`          | WebDriverIO tests for Tauri app (Linux)        |
-| `test/e2e-linux/wdio.conf.ts`         | WebDriverIO configuration                      |
-| `test/e2e-linux/docker/Dockerfile`    | Docker image for Linux E2E tests               |
-| `test/e2e-linux/docker/entrypoint.sh` | Xvfb/dbus setup for headless GUI               |
-| `scripts/e2e-linux.sh`                | Main script for Docker-based E2E tests         |
-| `playwright.config.ts`                | Playwright configuration                       |
+| File                                  | Description                                         |
+|---------------------------------------|-----------------------------------------------------|
+| `test/e2e-smoke/smoke.test.ts`        | Playwright tests for basic UI (browser-based)       |
+| `test/e2e-linux/app.spec.ts`          | WebDriverIO tests for Tauri app (Linux)             |
+| `test/e2e-linux/wdio.conf.ts`         | WebDriverIO configuration                           |
+| `test/e2e-linux/docker/Dockerfile`    | Docker image for Linux E2E tests                    |
+| `test/e2e-linux/docker/entrypoint.sh` | Xvfb/dbus setup for headless GUI                    |
+| `scripts/e2e-linux.sh`                | Main script for Docker-based E2E tests (+ VNC mode) |
+| `playwright.config.ts`                | Playwright configuration                            |
 
 ## Writing tests
 
@@ -153,6 +153,31 @@ Inside the container, you can:
 - Check the display: `echo $DISPLAY`
 - Inspect the environment
 
+### VNC mode (visual debugging with hot reload)
+
+VNC mode runs `pnpm dev` inside the Docker container with a VNC server, so you can see and
+interact with the Cmdr GUI in a browser while editing code on macOS:
+
+Honestly, it's a bit weird, the VM feels better, but this is a small change so good to have this as a quick backup.
+
+```bash
+cd apps/desktop
+pnpm test:e2e:linux:vnc
+```
+
+Once it starts, open the URL printed in the terminal (http://localhost:6090/vnc.html?autoconnect=true).
+You can also connect with a native VNC client (macOS Screen Sharing) at `vnc://localhost:5990`.
+
+How it works:
+- The container runs Xvfb + x11vnc + noVNC, forwarding the virtual display to your browser
+- `pnpm dev` starts Vite + Tauri inside the container
+- Source code is mounted from your host, so `.svelte`/`.ts` edits trigger Vite HMR (~1–3s reload)
+- Rust changes require restarting (`Ctrl+C` + re-run)
+- Terminal streams all Rust/Vite logs
+
+This is useful for debugging issues specific to the Linux/WebKitGTK environment, like keyboard
+events or GTK focus behavior that differ from macOS.
+
 ### Build caching
 
 The script uses Docker volumes to cache:
