features/src/desktop-lite

Light-weight Desktop (desktop-lite)

Adds a lightweight Fluxbox based desktop to the container that can be accessed using a VNC viewer or the web. GUI-based commands executed from the built-in VS code terminal will open on the desktop automatically.

Example Usage

"features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {}
}

Options

Options Id	Description	Type	Default Value
version	Currently Unused!	string	latest
noVncVersion	NoVnc Version	string	1.2.0
password	Enter a password for desktop connections	string	vscode
webPort	Enter a port for the VNC web client	string	6080
vncPort	Enter a port for the desktop VNC server	string	5901

Connecting to the desktop

This feature provides two ways of connecting to the desktop environment it adds. The first is to connect using a web browser. To do so:

1. Forward the noVNC port (6080 by default) to your local machine using either the forwardPorts property in devcontainer.json or the user interface in your tool (e.g., you can press F1 or Ctrl/Cmd+Shift+P and select Ports: Focus on Ports View in VS Code to bring it into focus).
2. Open the ports view in your tool, select the noVNC port, and click the Globe icon.
3. In the browser that appears, click the Connect button and enter the desktop password (vscode by default).

You can also connect to the desktop using a VNC viewer. To do so:

1. Connect to the environment from a desktop tool that supports the dev container spec (e.g., VS Code client).
2. Forward the VNC server port (5901 by default) to your local machine using either the forwardPorts property in devcontainer.json or the user interface in your tool (e.g., you can press F1 or Ctrl/Cmd+Shift+P and select Ports: Focus on Ports View in VS Code to bring it into focus).
3. Start your VNC Viewer and connect to localhost:5901. Note that you may need to bump up the color depth to 24 bits to see full color.
4. Enter the desktop password (vscode by default).

Customizing Fluxbox

The window manager is installed is Fluxbox. Right-click to see the application menu. In addition, any UI-based commands you execute inside the dev container will automatically appear on the desktop.

You can customize the desktop using Fluxbox configuration files. The configuration files are located in the .fluxbox folder of the home directory of the user you using to connect to the dev container ($HOME/.fluxbox).

If you add custom content to your base image or a Dockerfile in this location, the Feature will automatically use it rather than its default configuration.

See the Fluxbox menu documentation for format details. More information on additional customization can be found in Fluxbox's help and general documentation.

Resolving crashes

If you run into applications crashing, you may need to increase the size of the shared memory space allocated to your container. For example, this will bump it up to 1 GB in devcontainer.json:

"runArgs": ["--shm-size=1g"]

Or using Docker Compose:

services:
  your-service-here:
    # ...
    shm_size: '1gb'
    # ...

Installing a browser

If you need a browser, you can install Firefox ESR by adding the following to .devcontainer/Dockerfile:

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && apt-get install -y firefox-esr

If you want the full version of Google Chrome in the desktop:

1. Add the following to .devcontainer/Dockerfile

   RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
       && curl -sSL https://dl.google.com/linux/direct/google-chrome-stable_current_$(dpkg --print-architecture).deb -o /tmp/chrome.deb \
       && apt-get -y install /tmp/chrome.deb
   

2. Chrome sandbox support requires you set up and run as a non-root user. The common-utils script can do this for you, or you set one up yourself. Alternatively, you can start Chrome using google-chrome --no-sandbox

That's it!

OS Support

This Feature should work on recent versions of Debian/Ubuntu-based distributions with the apt package manager installed.

bash is required to execute the install.sh script.

---

Note: This file was auto-generated from the devcontainer-feature.json. Add additional notes to a NOTES.md.