Configuring Desktop Sessions

This page is for the people who own a cluster's definition. It covers how desktop sessions start on a node, what the node needs, and the Desktop session configuration settings that control the desktop your users get. For launching and using a desktop, see Desktop Sessions.

How a desktop starts

When a user launches a desktop, the ACTIVATE agent on the target node:

1. Downloads the desktop software from the platform (once per node, then cached), verifying each download against the platform's signed software manifest.
2. Starts a VNC server (TigerVNC's Xvnc) on a free display. The desktop resizes to fit the user's browser window.
3. Starts a desktop environment inside it, either from an Apptainer/Singularity container or from what is installed on the host (see Choosing the desktop environment).
4. Streams the display to the user's browser through ACTIVATE. Nothing on the node needs to accept inbound connections from the user.

The desktop runs as the user, with the user's home directory, groups, and file permissions.

Where software is installed

The downloads are a TigerVNC bundle (Xvnc plus the libraries, keyboard maps, and fonts it needs), a small fallback window manager (fluxbox and xterm), and, only when Apptainer mode is on, the platform's default XFCE container image.

Node requirements

• Linux. Desktop sessions aren't supported on macOS hosts.

• Host libraries. The bundled Xvnc needs libgbm.so.1 and libxshmfence.so.1, and TigerVNC 1.13 or later also loads libxcvt.so.0. Install them if your nodes lack them:

  Library	RHEL / Rocky	Debian / Ubuntu
  libgbm.so.1	mesa-libgbm	libgbm1
  libxshmfence.so.1	libxshmfence	libxshmfence1
  libxcvt.so.0	libxcvt	libxcvt0

  If the bundled Xvnc can't run, the agent falls back to a system-installed Xvnc. On RHEL 8 family hosts (RHEL, Rocky, Alma, CentOS, Oracle Linux 8) the agent prefers the system Xvnc when one is installed.

• Apptainer mode only: apptainer or singularity must be on the PATH or available through module load.

• GPU rendering only: see GPU-accelerated rendering.

Desktop session configuration

Desktop settings live on the cluster's Definition page, in the collapsed Desktop session configuration section. The section is available on cloud clusters and existing (on-premises) clusters. Managed clusters don't have this section; instead, an administrator picks the Session Node that hosts desktops.

You can change these settings while the cluster is running. New desktop sessions use the updated settings; sessions that are already open keep the settings they started with.

These settings travel with the cluster when you publish it to the Marketplace.

Choosing the desktop environment

There is no desktop picker: the environment depends on whether Apptainer is on.

Apptainer on. Every session runs XFCE from the container image, so all users get the same, reproducible desktop regardless of what is installed on the node. The agent picks the image in this order:

1. The SIF file path, if set and readable.
2. The platform-default XFCE image, downloaded and cached on the node.

If a node can't mount SIF images (common on STIG- or CIS-hardened systems), the agent unpacks the image into a sandbox directory and runs that instead.

Apptainer off. The agent uses the first desktop it finds installed on the host, in this order:

1. XFCE (xfce4-session)
2. MATE (mate-session)
3. Cinnamon (cinnamon-session)
4. GNOME (gnome-session)
5. LXDE (startlxde)
6. LXQt (lxqt-session)
7. KDE Plasma (startplasma-x11)
8. The bundled fluxbox window manager, or a host-installed openbox, fluxbox, IceWM, or twm
9. A bare xterm

To give users a particular host desktop, install it (and uninstall or avoid ones earlier in the list).

Bind paths

The container always mounts the user's home directory, plus the X11 socket, $XAUTHORITY, and $XDG_RUNTIME_DIR. Add the shared file systems your users need (project directories, scratch, software trees):

/scratch
/p/app:/opt/apps
/datasets:/datasets:ro

• /host/path mounts at the same path inside the container.
• /host/path:/container/path mounts it at a different path.
• Append :ro to mount read-only.

Each entry is passed to Apptainer's --bind option. If the host path doesn't exist on a node, the agent skips it rather than failing the session. Bind paths have no effect when Apptainer is off, because the host desktop already sees the host's file systems.

Init script

Use the init script for setup every desktop session needs, for example:

module load matlab paraview
export LM_LICENSE_FILE=27000@license.example.com
 
# Add site applications to the desktop menu
mkdir -p ~/.local/share/applications
ln -sf /p/app/desktop-entries/*.desktop ~/.local/share/applications/

The desktop terminal in Apptainer mode

In Apptainer mode, the desktop's terminal opens on the cluster host, so users see the host PATH, modules, scheduler commands, and installed software. To get a shell inside the desktop container instead, users open Container Terminal under Applications → System.

GPU-accelerated rendering

By default, desktops render in software, which is fine for most work but slow for 3D visualization. With GPU-accelerated rendering (VirtualGL) on, OpenGL applications render on the node's NVIDIA GPU through VirtualGL's EGL back-end. You don't need a 3D X server or vglserver_config.

Every node that may host a desktop needs:

• An NVIDIA GPU and driver (nvidia-smi -L must succeed).
• VirtualGL installed, with vglrun on the PATH (dnf install VirtualGL on RHEL and Rocky).
• Access to the GPU render node (/dev/dri/renderD*) for the user running the session, typically through the render or video group.

The agent re-checks these on every session start. If anything is missing, the session still starts with software rendering, and the agent logs why (see Troubleshooting). In Apptainer mode the agent also passes the GPU into the container (--nv and /dev/dri) and runs VirtualGL inside it.

Custom desktop wallpaper

Organization administrators can set the wallpaper every new desktop session shows. See Desktop Wallpaper in Customizing Organization Theme.

Troubleshooting

Desktop logs are written to the user's ~/.vnc directory on the node that ran the session:

The agent's own log records the GPU decision on every launch as VNC GPU rendering decision, with a mode (accelerated or software) and a reason.