| --- |
| title: Ubuntu Desktop |
| emoji: 🐧 |
| colorFrom: indigo |
| colorTo: blue |
| sdk: docker |
| pinned: false |
| --- |
| |
| # 🐧 Ubuntu Desktop on Hugging Face Spaces |
|
|
| A browser-accessible **Ubuntu 24.04 XFCE Desktop** running on a free Hugging Face |
| Docker Space — inspired by Android Termux + PRoot-Distro workflows, adapted for |
| cloud deployment with zero manual setup. |
|
|
| --- |
|
|
| ## ✨ What You Get |
|
|
| | Feature | Detail | |
| |---|---| |
| | **Desktop** | Ubuntu 24.04 + XFCE4, accessible from any browser | |
| | **VNC** | TigerVNC (Xvnc) at 1280×720, 16-bit colour, 24 FPS | |
| | **Browser Access** | noVNC via WebSocket — no VNC client needed | |
| | **Persistent Storage** | All data stored in `/data` — survives Space restarts | |
| | **Dashboard** | Flask app with live CPU / RAM / disk stats + log viewer | |
| | **Browser** | Firefox ESR pre-installed | |
| | **Free CPU Tier** | Optimised for low RAM + CPU (≈ 400 MB idle) | |
|
|
| --- |
|
|
| ## 🚀 Deployment to Hugging Face Spaces |
|
|
| ### Prerequisites |
|
|
| - A [Hugging Face](https://huggingface.co) account |
| - Git installed locally (or use the HF web UI) |
|
|
| ### Step 1 — Create a new Space |
|
|
| 1. Go to **huggingface.co/new-space** |
| 2. Choose **Docker** as the Space SDK |
| 3. Set hardware to **CPU Basic** (free tier) |
| 4. Enable **Persistent Storage** in the Space settings (required for `/data`) |
|
|
| ### Step 2 — Upload the files |
|
|
| Either use the HF web editor to paste each file, or clone the Space repo and push: |
|
|
| ```bash |
| git clone https://huggingface.co/spaces/<YOUR_USERNAME>/<YOUR_SPACE_NAME> |
| cd <YOUR_SPACE_NAME> |
| |
| # Copy all project files here |
| cp -r /path/to/hf-ubuntu-space/* . |
| |
| git add . |
| git commit -m "Initial Ubuntu Desktop Space" |
| git push |
| ``` |
|
|
| ### Step 3 — Wait for the build |
|
|
| The first build takes **5–8 minutes** (downloading Ubuntu + XFCE packages). |
| Watch the **Build Logs** tab in the Space UI. |
|
|
| ### Step 4 — Access your desktop |
|
|
| Once the Space shows **Running**, click the **App** tab, or open: |
|
|
| ``` |
| https://<username>-<spacename>.hf.space |
| ``` |
|
|
| Click **🖥 Launch Desktop** to open the noVNC browser desktop. |
|
|
| --- |
|
|
| ## 🖥 Browser Desktop Access |
|
|
| | URL | Purpose | |
| |---|---| |
| | `https://…hf.space/` | Launcher page (recommended) | |
| | `https://…hf.space/vnc/vnc.html` | noVNC direct (raw interface) | |
| | `https://…hf.space/dashboard` | System stats dashboard | |
|
|
| The launcher page auto-detects your Space's hostname and builds the correct |
| WebSocket URL for noVNC — this is important because HF Spaces use Cloudflare |
| proxying where the port is always 443 externally. |
|
|
| ### Mobile browsers |
|
|
| noVNC works on mobile. Use the scale/resize button (⤢) in the noVNC toolbar |
| to fit the 1280×720 desktop to your screen. |
|
|
| --- |
|
|
| ## 💾 Persistent Storage |
|
|
| All state lives under `/data` (Hugging Face's persistent volume): |
|
|
| ``` |
| /data/ |
| ├── home/ ← ubuntu user home (~/.bashrc, Desktop, etc.) |
| ├── workspace/ ← your project files (persists forever) |
| ├── downloads/ ← browser and wget downloads |
| ├── firefox/ ← Firefox profile (bookmarks, passwords, etc.) |
| ├── xfce/ ← XFCE session config, wallpaper, themes |
| ├── vnc/ ← VNC server state + xstartup |
| ├── logs/ ← all service logs |
| └── cache/ ← app-level cache |
| ``` |
|
|
| > **Note:** You must enable **Persistent Storage** in your Space settings. |
| > Without it `/data` is ephemeral and resets on every restart. |
|
|
| --- |
|
|
| ## ⚙️ PRoot-Distro Similarities |
|
|
| This Space simulates the Termux + PRoot-Distro workflow: |
|
|
| | Termux / PRoot | This Space | |
| |---|---| |
| | `pkg install proot-distro` | Base Docker layer | |
| | `proot-distro install ubuntu` | `FROM ubuntu:24.04` in Dockerfile | |
| | `proot-distro login ubuntu` | Container starts automatically | |
| | `~` (Termux home) | `/data/home` (persisted) | |
| | Internal storage | `/data/workspace` | |
|
|
| The key difference is that this runs Docker natively (not PRoot), giving full |
| kernel-level isolation without the overhead of a userspace chroot. |
|
|
| --- |
|
|
| ## 🔧 Configuration |
|
|
| ### Environment variables (set in Space settings) |
|
|
| | Variable | Default | Description | |
| |---|---|---| |
| | `VNC_PASSWORD` | _(empty)_ | Set a VNC password (optional; localhost-only anyway) | |
| | `RESOLUTION` | `1280x720` | Desktop resolution | |
| | `COLOR_DEPTH` | `16` | VNC colour depth (16 or 24) | |
|
|
| ### Changing resolution |
|
|
| Edit `supervisord.conf`, update the Xvnc command: |
|
|
| ```ini |
| command=Xvnc :1 -geometry 1920x1080 -depth 24 ... |
| ``` |
|
|
| --- |
|
|
| ## 🛠 Troubleshooting |
|
|
| ### Desktop doesn't load / black screen |
|
|
| 1. Open the **Dashboard** → check all services show **Running** |
| 2. Check **Xvnc** and **XFCE4** logs for errors |
| 3. Try restarting XFCE4 from the dashboard restart button |
|
|
| ### "Failed to connect to server" in noVNC |
|
|
| - Make sure you're using the **launcher page** (`/`) not a hard-coded URL |
| - The WebSocket path must be `/websockify` — check the URL bar in noVNC shows the correct host |
|
|
| ### Space keeps sleeping |
|
|
| HF free CPU Spaces sleep after ~15 min of no browser traffic. This is expected. |
| Wake it by opening the Space URL. Your `/data` files are always preserved. |
|
|
| ### High memory usage |
|
|
| XFCE4 uses ~300–400 MB at idle. With Firefox open, expect 800 MB+. The free |
| CPU tier has 16 GB RAM, so this is fine. If you see OOM kills, close unused |
| browser tabs in the desktop. |
|
|
| ### Logs |
|
|
| All logs are in `/data/logs/` and viewable from the Dashboard log viewer: |
|
|
| ``` |
| /data/logs/supervisord.log |
| /data/logs/xvnc.log / xvnc_err.log |
| /data/logs/xfce4.log / xfce4_err.log |
| /data/logs/websockify.log |
| /data/logs/dashboard.log |
| /data/logs/nginx.log / nginx_error.log |
| ``` |
|
|
| --- |
|
|
| ## 🏗 Architecture |
|
|
| ``` |
| Browser (HTTPS :443) |
| │ |
| ▼ |
| nginx :7860 (HF Spaces default port) |
| ├─ / ──────────────────────── Launcher HTML (auto-builds WSS URL) |
| ├─ /vnc/ ─────────────────── noVNC static assets |
| ├─ /websockify ───────────── WebSocket proxy ──► websockify :6080 |
| │ │ |
| │ Xvnc :5901 |
| │ XFCE4 session |
| ├─ /dashboard ────────────── Flask app :5000 |
| └─ /api/ ─────────────────── Flask REST API :5000 |
| ``` |
|
|
| --- |
|
|
| ## 📄 Licence |
|
|
| MIT — use freely, no warranties. |
|
|
