readme

README.md

@@ -0,0 +1,61 @@
+# Ubuntu Desktop Sandbox (Docker + VNC + noVNC)
+
+A headless Ubuntu 24.04 container with an XFCE desktop, TigerVNC, and a noVNC web client. Open a full desktop in the browser at `http://localhost:6901/vnc.html`.
+
+## Quick Start
+
+```bash
+cp .env.example .env    # set VNC_PASSWORD (and optionally RESOLUTION)
+docker compose up -d --build
+```
+
+Then open <http://localhost:6901/vnc.html> and log in:
+
+- Username: `ubuntu`
+- Password: the value of `VNC_PASSWORD` from your `.env`
+
+## Configuration
+
+Variables are read from `.env` (see `.env.example`):
+
+| Variable       | Default     | Description                          |
+| -------------- | ----------- | ------------------------------------ |
+| `VNC_PASSWORD` | `changeme`  | Login password for the `ubuntu` user |
+| `RESOLUTION`   | `1280x800`  | Desktop geometry                     |
+
+> The container starts with a warning if `VNC_PASSWORD` is still `changeme`. Set it before using the box.
+
+## Common Commands
+
+```bash
+docker compose up -d --build   # build and start
+docker compose logs -f         # follow container logs
+docker exec -it xubuntu_sandbox bash   # shell inside the desktop
+docker compose stop            # stop (keeps volume)
+docker compose down -v         # stop and delete the persistent volume
+```
+
+## Ports
+
+| Port | Service                |
+| ---- | ---------------------- |
+| 6901 | noVNC web client (browser access) |
+| 5901 | TigerVNC (raw VNC, for native clients) |
+
+## How It Works
+
+- **Desktop**: XFCE4 on Ubuntu 24.04, started by `scripts/xstartup` via `dbus-launch`.
+- **VNC server**: TigerVNC on display `:1`. This build does not ship `vncpasswd`, so it uses VNC's *Plain* security type and authenticates against the Unix `ubuntu` account via PAM — which is why the login password is set with `chpasswd` from `VNC_PASSWORD` at container start (`scripts/entrypoint.sh`).
+- **Web access**: noVNC is served by `websockify` on port 6901, proxying to the VNC server.
+- **Persistence**: the named volume `xubuntu_home` is mounted at `/home/ubuntu`, so your files, installed packages, and settings survive container rebuilds. (The VNC password is *not* persisted — it is reapplied from `VNC_PASSWORD` on every start.)
+- The `ubuntu` user has passwordless `sudo`.
+
+## Files
+
+```
+Dockerfile          Ubuntu 24.04 + XFCE + TigerVNC + noVNC
+docker-compose.yml  Service definition (ports, volume, env)
+scripts/entrypoint.sh  Sets password, starts VNC + websockify
+scripts/xstartup        XFCE session launcher for VNC
+.env.example        Default configuration
+```