docker-selkies-glx-desktop

docker-selkies-glx-desktop

Part of

KDE Plasma desktop container for Selkies on an X.Org server of its own, built on the Selkies base container: a complete remote desktop streamed over WebSockets or WebRTC to a browser, with the GPU driving the whole X server. OpenGL and Vulkan reach applications through the vendor’s own X driver, with nothing translating in between: the proprietary NVIDIA driver, or the modesetting driver on any GPU with a kernel KMS driver (AMD, Intel). The X server is the container’s own, so no /tmp/.X11-unix host socket or host X configuration is involved, and one GPU carries one container.

Use docker-selkies-egl-desktop for the same desktop on the base’s own display servers, reaching the GPU through EGL without an X.Org server: it shares one GPU between many containers, runs without a GPU at all, and offers the Wayland backend.

Please read Troubleshooting first, then use Discord or GitHub Discussions for support questions. Please only use Issues for technical inquiries or bug reports.

What is in the image

The Selkies base container supplies everything but the desktop and the X server: PipeWire audio, the GPU runtime wiring for NVIDIA, VA-API, and Vulkan, the gamepad and webcam plumbing, s6 service supervision, an embedded coTURN server for the WebRTC transport, and Selkies itself. This image replaces the base’s framebuffer server with an X.Org server on the GPU (the xorg service, configured at start by selkies-xorg-config for the GPU the session was given), and adds KDE Plasma on X11 (plasma-desktop with Dolphin, Konsole, KWrite, Gwenview, Ark, and System Settings), Firefox and Google Chrome, and the proot-apps runner behind the dashboard’s apps panel, which installs portable applications into the home directory without touching the image, Steam behind a bubblewrap stand-in that needs no user namespaces, Wine Staging with winetricks, VLC, LibreOffice, and the KDE application set.

The NVIDIA X server modules (nvidia_drv.so and the GLX server module) come in with the driver’s libraries from the NVIDIA Container Toolkit v1.20.1 or higher; under a runtime that injects the libraries alone, the first start on an NVIDIA GPU lifts the two out of the driver installer matching the host driver version, the only other place they are shipped, and a container that keeps its filesystem keeps them across restarts. The same installer supplies the driver’s 32-bit client libraries where the runtime brings none in, so the first start may fetch it either way. NVIDIA_DRIVER_VERSION overrides the version to fetch when the host’s cannot be read.

This image is X11 only; the base’s Wayland backend is not offered here. Container tags are 26.04 for the current Ubuntu 26.04 build, latest for the same, and persistent tags of the form 26.04-20260101010101 for a specific build.

Usage

Running with Docker

1. Run the container with Docker or Podman.

With an NVIDIA GPU (the NVIDIA Container Toolkit v1.20.1 or higher is required):

docker run --name xgl -it -d --gpus 1 --runtime nvidia --shm-size=2g -e TZ=UTC -e PASSWD=mypasswd -e VIDEO_PORT=DFP -p 8080:8080 ghcr.io/selkies-project/selkies-glx-desktop:26.04

With an AMD or Intel GPU, pass the DRM devices in instead. The session user inside the container (uid 1000) must be able to open them, which --group-add covers when the host’s render and video groups own the nodes, and no X server or compositor on the host may be driving that GPU:

docker run --name xgl -it -d --device=/dev/dri:rwm --group-add="$(getent group render | cut -d: -f3)" --group-add="$(getent group video | cut -d: -f3)" --shm-size=2g -e TZ=UTC -e PASSWD=mypasswd -p 8080:8080 ghcr.io/selkies-project/selkies-glx-desktop:26.04

Alternatively, use Docker Compose by editing docker-compose.yml:

# Start the container from the path containing docker-compose.yml
docker compose up -d
# Stop the container
docker compose down

--shm-size=2g matters because the browsers inside the desktop crash on Docker’s 64 MB default. Replace mypasswd with your own password. The container must NOT be run in privileged mode. The first start on an NVIDIA GPU takes a minute longer while the driver installer is fetched.

2. Connect to the web server on port 8080 with a browser. You may also put a reverse proxy in front of it for external connectivity.

The container serves HTTPS by default on a certificate it mints per install, so the browser warns once until you trust it or name a real certificate with -e SELKIES_HTTPS_CERT= and -e SELKIES_HTTPS_KEY=; -e SELKIES_ENABLE_HTTPS=false serves plain HTTP for a deployment that terminates TLS in front of the container.

The login is ubuntu with the password from PASSWD (which is also the container’s Linux user password) unless SELKIES_BASIC_AUTH_USER and SELKIES_BASIC_AUTH_PASSWORD name another one.

3. If the desktop loads but does not stream, or streams very slowly, read WebRTC and Firewall Issues. The default WebSocket transport needs nothing but the web port. The WebRTC transport (-e SELKIES_MODE=webrtc) needs a TURN server or host networking, because you are self-hosting WebRTC.

Running with Kubernetes

1. Create the Kubernetes Secret with your password (change keys and values as adequate):

kubectl create secret generic my-pass --from-literal=my-pass=YOUR_PASSWORD

NOTE: Replace YOUR_PASSWORD with your desired password, and change the name my-pass to your preferred name of the Kubernetes secret with the xgl.yml file changed accordingly as well. It is possible to skip this step and provide the password with value: in xgl.yml, but this exposes the password in plain text.

2. Create the pod after editing xgl.yml to your needs; explanations are in the file:

kubectl create -f xgl.yml

The file requests an NVIDIA GPU through the NVIDIA device plugin. AMD and Intel GPUs are requested through their own device plugins (amd.com/gpu, gpu.intel.com/i915) in the same resources: section; the node must not run an X server or compositor on that GPU.

3. Connect to the web server on port 8080 through the ingress or reverse proxy your cluster provides. The login is the same as with Docker.

4. If the desktop loads but does not stream, read WebRTC and Firewall Issues.

Running with Apptainer

On a cluster without Docker, the image runs under Apptainer as an ordinary user, pulled straight from the registry, and its X.Org server runs on the GPU without root. Besides what the Selkies documentation explains for every image (a display number and a port no other session on the node uses, a private /tmp, a home directory of your own, --writable-tmpfs, --nv), the X server needs the host driver’s two X server modules at the paths it loads them from. An Apptainer whose --nv binds them there needs nothing more; check with

apptainer exec --nv docker://ghcr.io/selkies-project/selkies-glx-desktop:26.04 ls /usr/lib/xorg/modules/drivers/nvidia_drv.so

and when the file is missing, bind the two modules from the host; the version in the file names is the host driver’s:

#!/bin/bash
N=$((RANDOM % 900 + 100))
PORT=$((RANDOM % 10000 + 20000))
mkdir -p "$HOME/selkies/home" "$HOME/selkies/tmp"
X=/usr/lib/xorg/modules
V=$(nvidia-smi --query-gpu=driver_version --format=csv,noheader | head -n 1)
apptainer run --nv --writable-tmpfs --contain --cleanenv \
    --home "$HOME/selkies/home:/home/ubuntu" -B "$HOME/selkies/tmp:/tmp" -B /dev/dri \
    -B "$X/drivers/nvidia_drv.so:$X/drivers/nvidia_drv.so" \
    -B "$X/extensions/libglxserver_nvidia.so.$V:$X/extensions/libglxserver_nvidia.so.$V" \
    --env "DISPLAY=:$N,SELKIES_PORT=$PORT,PASSWD=mypasswd" \
    docker://ghcr.io/selkies-project/selkies-glx-desktop:26.04

Reach it with ssh -L 8080:<node>:$PORT <login-node> and open https://localhost:8080. Where the host keeps the modules elsewhere, find / -name nvidia_drv.so finds them; a module bound under its plain name (libglxserver_nvidia.so) is accepted too. Without the modules the image fetches them from the driver installer matching the host on every start, which needs the node to reach NVIDIA’s download server. --nvccli stages the modules exactly when --nv does.

Configuration

Everything Selkies reads is an environment variable named in docs/settings.md (selkies --help inside the container lists the same). The ones this image adds or that matter most:

The video encoder, the video and audio bitrates, the frame rate, and the UI scaling are chosen from the web interface and are not set in the environment; a single value in SELKIES_ENCODER or SELKIES_SCALING_DPI locks that choice.

The SELKIES_TURN_* variables configure the WebRTC transport, and DISABLE_ZINK is preset here: OpenGL goes through the X server’s own GLX vendor, the NVIDIA driver included, rather than through Zink.

The X server

selkies-xorg-config writes /etc/X11/xorg.conf at every start for the GPU the base container resolved for the session (the SELKIES_AUTO_GPU pick, or SELKIES_RENDER_DRI), read back from its render node; an NVIDIA GPU exposed without a DRM node is found through the driver’s own /proc tree. NVIDIA GPUs take the nvidia driver with the video port from VIDEO_PORT reported connected, so RandR has an output to hang the client’s sizes on and a monitor plugged into that port shows the desktop; every other GPU takes the modesetting driver over its /dev/dri node, and the configured mode goes on the first connected output: a monitor, or a display emulator plug where there is none. The server runs as the session user, sharing a virtual terminal it never switches to; the log is at /tmp/runtime-ubuntu/Xorg.log inside the container.

On X11 the Plasma shell lays its panels and wallpaper out for the DPI it started at and follows a later change only in part, so the image replaces the shell when the dashboard’s UI scaling changes: the desktop lays out afresh at the new size within a few seconds, and open windows stay where they are. A second display is opened from the dashboard in a second browser window: each display is a RandR monitor on the X server’s one output. The Plasma shell lays its panels and desktop out per monitor, and the image’s kwin_x11 is rebuilt to take its screens from those monitors too (patches/kwin-x11/): a stock kwin_x11 reads them from RandR CRTCs, of which that output has one, and would span both displays with a maximized window. A server without a connected RandR output is a desktop with no screen: the toolkits take their screens from the outputs, the Plasma shell lays its panels and desktops out by the connected ones, and Selkies resizes only a connected one, so it lays out nothing and the session is a black stream, even where a mode lights a disconnected output. Most datacenter GPUs carry virtual display devices that VIDEO_PORT lights like any other and never reach this; a few boards report no display device at all, an AMD or Intel GPU with nothing plugged in has only disconnected outputs, and VIDEO_PORT=none asks for the same thing. Either way the service says so and runs the base container’s framebuffer server in place of this one, which serves the same session on an output of its own and keeps the GPU: its glamor draws on the render node, GLX still goes to the vendor’s own client library through DRI3, and the encoders are untouched. What the move costs is the capture path, which grabs the screen through shared memory instead of reading it where the driver composited it; the selkies service restarts once the framebuffer server answers, so the size it presets lands there and not on the server replaced. Where the GPU can drive a display, the native server keeps the desktop.

Apps panel

The dashboard’s apps panel installs applications from the proot-apps catalogue into the home directory. They persist with the home directory (mount a volume at /home/ubuntu to keep them) and never touch the image. sudo apt-get install works inside the session as well, through fakeroot, for packages the image should carry; sudo-root is the real thing, for device nodes and permissions only.

Steam

Steam is installed on x86, and starts from the application menu or steam like anywhere else. The client containerizes its browser helper and every game with bubblewrap, which needs a user namespace this container does not have, so proot-next’s bwrap mode stands in for it behind Steam’s own launcher. The Steam Linux Runtime is used exactly as Valve ships it, so native Linux games get the libraries they were built against and Proton runs through the runtime it asks for; enable Steam Play for all titles under Steam > Settings > Compatibility to pick a Proton version. Games and Proton prefixes live in the home directory, so mount a volume at /home/ubuntu to keep them.

Wine

Wine Staging is installed on x86 from WineHQ’s own repository, with winetricks. A Windows application runs under it directly, and the prefix lives in the home directory like everything else. Steam’s own Windows games go through Proton instead, which the Steam section above covers.

WebRTC and Firewall Issues

This section applies only to the WebRTC transport (SELKIES_MODE=webrtc, or switching to it in the web interface); the default WebSocket transport needs only the web port.

Self-hosted WebRTC needs a TURN server when the client and the container cannot reach each other directly, which is the case behind most NATs and firewalls, and always inside Docker’s network isolation. Choose one of the following.

• Internal TURN server: the container runs its own coTURN when it has no external one. Publish its ports with -p 3478:3478 -p 3478:3478/udp -p 65532-65535:65532-65535 -p 65532-65535:65532-65535/udp (or uncomment them in docker-compose.yml / xgl.yml) and set -e TURN_MIN_PORT=65532 -e TURN_MAX_PORT=65535 to that range, which must contain at least two ports no other process uses. Set -e SELKIES_TURN_HOST= to the address clients reach the container on when it is not the public one, and -e SELKIES_TURN_PROTOCOL=tcp when UDP cannot be used, at the cost of latency.

• Host networking: --network=host (or network_mode: 'host' / hostNetwork: true) with UDP and TCP ports 49152–65535 open in the host’s firewall usually just works. Display :20 must then be free on the host, and a second container needs its own -e DISPLAY=:22 -e SELKIES_PORT=8082; the cluster may not allow it.

• External TURN server: set SELKIES_TURN_HOST and SELKIES_TURN_PORT, then either SELKIES_TURN_SHARED_SECRET (time-limited shared secret authentication) or both SELKIES_TURN_USERNAME and SELKIES_TURN_PASSWORD (long-term credentials), never both methods at once. SELKIES_TURN_PROTOCOL=tcp when UDP is blocked; SELKIES_TURN_TLS=true when the TURN server has a valid certificate. A TURN REST API is named with SELKIES_TURN_REST_URI alone. The Selkies firewall documentation covers deploying one; with Kubernetes, keep the credentials in a Secret the way xgl.yml shows.

Troubleshooting

The container does not work with an NVIDIA GPU.

The container does not work with an AMD or Intel GPU.

The container does not work with a resolution above 2560 x 1600, or with a laptop or hybrid GPU.

I want to share one GPU with multiple containers, or run without a GPU.

Use docker-selkies-egl-desktop. An X server owns its GPU, so two of them cannot share one, and this image has no framebuffer fallback.

The container does not work when a desktop or X server runs on the host.

Section "ServerFlags"
    Option "AutoAddGPU" "False"
EndSection

The browser inside the desktop, or another application, crashes at once.

Vulkan does not work.

I want to customize this container.

Build on it the way docs/development.md describes: use this image as the base and replace or add s6 service files under /etc/service/. Every service here is one run script: xorg (the X server, configured by selkies-xorg-config), plasma (the session), dbus-session (the session bus), and the base’s own.

Building

docker build -t selkies-glx-desktop --build-arg BASE_IMAGE=ghcr.io/selkies-project/selkies/base:latest-ubuntu26.04 .

BASE_IMAGE is any Ubuntu 26.04 Selkies base container, by tag or digest; SELKIES_REF names the Selkies revision the shared helper scripts are taken from (main).

Every download is checked against the hash its source publishes: the newest releases against the SHA-256 GitHub records for them, files at a revision against the hash GitHub names for them, and the apt repositories’ keys against their fingerprints. Those GitHub lookups go through its API, which serves 60 requests an hour without a token; a build that runs short passes one as a secret: GITHUB_TOKEN=... docker build --secret id=github_token,env=GITHUB_TOKEN ....

This project has been developed and is supported in part by the Seok-San Yonsei Medical Scientist Training Program (MSTP) Song Yong-Sang Scholarship and a Student Research Bursary from the Song-Dang Institute for Cancer Research, from Yonsei University College of Medicine, the MD-PhD/Medical Scientist Training Program (MSTP) and the Young Korean Medical Education & Research Secretariat (Y-KOMERS) Medical Student Overseas Training Bootcamp Program, through the Korea Health Industry Development Institute (KHIDI), funded by the Ministry of Health & Welfare, Republic of Korea, the KREONET Advanced Research Program Grant by the Korea Institute of Science and Technology Information (KISTI), the National Research Foundation of Korea (NRF) grant funded by the Ministry of Science and ICT, Republic of Korea (No. RS-2026-NR121335), the National Research Platform (NRP) and the Cognitive Hardware and Software Ecosystem Community Infrastructure (CHASE-CI) at the University of California, San Diego, by funding from the National Science Foundation (NSF), with awards #1540112, #1541349, #1730158, #1826967, #2100237, #2112167, #2120019, #2138811, and #2616251, as well as additional funding from community partners, infrastructure utilization from the Open Science Grid Consortium, supported by the National Science Foundation (NSF) awards #1836650 and #2030508, and infrastructure utilization from the Chameleon testbed, supported by the National Science Foundation (NSF) awards #1419152, #1743354, #2027170, and #2431425.

_{^{* Funding agencies including, but not limited to the National Science Foundation, remain neutral with regard to jurisdictional claims in published articles and software code of this Code Repository. In the context including, but not limited to this Code Repository, as well as in the context including, but not limited to any and all derivative works based on this Code Repository, all trademarks, trade names, logos, patents, or any and all other forms of external intellectual property, that are mentioned or used, unless otherwise stated, are the property of their respective owners, including but not limited to, The Linux Foundation®, Linus Torvalds, The Apache Software Foundation, Canonical Ltd., Google LLC, Alphabet Inc., NumFOCUS Foundation, Anaconda Inc., conda-forge, Project Jupyter, Coder Technologies, Inc., Docker®, Inc., SchedMD LLC, NVIDIA Corporation, Intel Corporation, Advanced Micro Devices, Inc., Valve Corporation, Epic Games, Inc., Unity Software Inc., Cendio AB, RealVNC® Limited, Amazon.com, Inc., Amazon Web Services, Inc., or its affiliates including but not limited to NICE s.r.l. or NICE USA LLC, Microsoft Corporation, Cloudflare, Inc., Oracle Corporation, StarNet Communications Corporation, TeamViewer SE, Fabrice Bellard, Moonlight Project, and LizardByte. Every best effort has been undertaken to properly identify and attribute trademarks, trade names, logos, patents, or any and all other forms of external intellectual property to their respective owners, unless otherwise stated, wherever possible and practical. The inclusion of such trademarks, trade names, logos, patents, or any and all other forms of external intellectual property in association with this project, unless otherwise stated, serves solely for the purpose of description and must never be construed as an indication of affiliation, competition, endorsement, or a challenge to any and all legal standings of the trademarks, trade names, logos, patents, or any and all other forms of external intellectual property. All project contributors, maintainers, owners, or organizations agree to not willfully breach or infringe legal regulations, in any and all global law, regarding trademarks, trade names, logos, patents, or any and all other forms of external intellectual property. Therefore, all project contributors, maintainers, owners, or organizations, are immune to, and are not to be in any and all cases held legally liable for, any and all jurisdictional claims on trademarks, trade names, logos, patents, or any and all other forms of external intellectual property. No component of this Code Repository is an official product of Google LLC or Alphabet Inc.}}