# 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
```