From 79c9987bc6b580eab015f9108e52b5fdb65917f5 Mon Sep 17 00:00:00 2001 From: app/github-actions Date: Mon, 2 Nov 2026 14:43:48 +0000 Subject: [PATCH 1/3] pr commit From 5eac3a4cd04283261fca7eee18d532c0ad962d72 Mon Sep 17 00:00:00 2001 From: aldmbmtl Date: Mon, 2 Nov 2026 10:07:28 -0500 Subject: [PATCH 2/3] Updated to disable VGL and Zink by default with the option to opt in now. --- Dockerfile | 3 ++- common/root/opt/helios/startwm.sh | 18 +++++++++--------- compose.yml | 2 +- docs/deploy-usage.md | 3 ++- 4 files changed, 14 insertions(+), 12 deletions(-) diff --git a/Dockerfile b/Dockerfile index 41420b81..8c0b1d46 100644 --- a/Dockerfile +++ b/Dockerfile @@ -85,7 +85,8 @@ ENV PERL5LIB=/usr/local/bin ENV PULSE_RUNTIME_PATH=/tmp/pulse ENV NVIDIA_DRIVER_CAPABILITIES=all ENV IDLE_TIME=30 -ENV DISABLE_ZINK=false +ENV DISABLE_ZINK=true +ENV DISABLE_VGL=true ENV REMOTE_PROTOCOL=selkies ENV XDG_SESSION_TYPE=x11 diff --git a/common/root/opt/helios/startwm.sh b/common/root/opt/helios/startwm.sh index d0e0ee4e..aa959075 100644 --- a/common/root/opt/helios/startwm.sh +++ b/common/root/opt/helios/startwm.sh @@ -1,7 +1,7 @@ #!/bin/bash -# Enable Nvidia GPU support if detected -if which nvidia-smi && [ "${DISABLE_ZINK}" == "false" ]; then +# Enable ZINK acceleration if DISABLE_ZINK is "false" +if [ "${DISABLE_ZINK}" == "false" ]; then export LIBGL_KOPPER_DRI2=1 export MESA_LOADER_DRIVER_OVERRIDE=zink export GALLIUM_DRIVER=zink @@ -119,18 +119,18 @@ restore_session() { restore_session || true if [ -x /usr/bin/xfce4-session ]; then - if [[ -n "$DISABLE_VGL" ]]; then - # Run without vglrun if DISABLE_VGL is set + if [ "${DISABLE_VGL}" == "false" ]; then + # DISABLE_VGL is "false" → enable vglrun (matches DISABLE_ZINK pattern) echo - echo ">>> Running without vglrun as DISABLE_VGL is set <<<" + echo ">>> Running with vglrun <<<" echo - exec dbus-launch --exit-with-session /usr/bin/xfce4-session 2>&1 + exec vglrun -d "$chosen" dbus-launch --exit-with-session /usr/bin/xfce4-session 2>&1 else - # Default: wrap in vglrun + # DISABLE_VGL is "true" or anything else → disable vglrun echo - echo ">>> Running with vglrun <<<" + echo ">>> Running without vglrun <<<" echo - exec vglrun -d "$chosen" dbus-launch --exit-with-session /usr/bin/xfce4-session 2>&1 + exec dbus-launch --exit-with-session /usr/bin/xfce4-session 2>&1 fi else echo "Desktop Environment not found." diff --git a/compose.yml b/compose.yml index ac275af6..95ac2c15 100644 --- a/compose.yml +++ b/compose.yml @@ -16,7 +16,7 @@ services: - USER=helios - UID=5040 - SUDO=true -# - DISABLE_VGL=1 + # - DESKTOP_FILES="/desktops/*.desktop:/tmp/*.desktop" # - IDLE_TIME=1 # - PASSWORD=password diff --git a/docs/deploy-usage.md b/docs/deploy-usage.md index fa5a288c..c656e2c9 100644 --- a/docs/deploy-usage.md +++ b/docs/deploy-usage.md @@ -11,7 +11,8 @@ Environment variables are used to configure the Helios container. The following | GID | POSIX compliant gid for the user | | | PASSWORD | Password set for the user. Required for DCV native client direct-connect (port 8443) | | | IDLE_TIME | Trigger the idle hook after x minutes. Previously used by the [auto shutdown plugin](plugins-autoshutdown.md), which is deprecated as of Genesis `v5.2.0` / Orion Workspaces `v4.3.0` in favor of Orion's built-in auto shutdown / auto hibernate | | -| DISABLE_VGL | Disable VirtualGL Wrapper around the entire desktop session. You will need to manually run applications that require it via `vglrun` | | +| DISABLE_VGL | Disable VirtualGL Wrapper around the entire desktop session. Set to `false` to use vglrun (default: `true`, vglrun disabled). Set to `true` (or any value) to run without vglrun. Matches the pattern of DISABLE_ZINK. | | +| DISABLE_ZINK | Disable ZINK acceleration. Set to `false` to enable ZINK (default: `true`, ZINK disabled). Set to `true` (or any value) to disable ZINK. Matches the pattern of DISABLE_VGL. | | | DESKTOP_FILES | Paths separated by `:`. For example, `/some/path/1/*.desktop:/some/*/2/*.desktop` | | | PREFIX | Prefix for URL for use behind a reverse proxy, both slashes required, e.g. `/custom/prefix/` | | | SELKIES_FRAMERATE | Set framerate as a range (e.g., `15-60`) or a fixed value (e.g., `30`) | | From ff24805f52a56ee0e10cdae4ce2471f0fb092299 Mon Sep 17 00:00:00 2001 From: aldmbmtl Date: Mon, 2 Nov 2026 10:58:09 -0500 Subject: [PATCH 3/3] Updated docs --- Dockerfile | 2 +- docs/deploy-usage.md | 86 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 84 insertions(+), 4 deletions(-) diff --git a/Dockerfile b/Dockerfile index 8c0b1d46..f05da70c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -86,7 +86,7 @@ ENV PULSE_RUNTIME_PATH=/tmp/pulse ENV NVIDIA_DRIVER_CAPABILITIES=all ENV IDLE_TIME=30 ENV DISABLE_ZINK=true -ENV DISABLE_VGL=true +ENV DISABLE_VGL=false ENV REMOTE_PROTOCOL=selkies ENV XDG_SESSION_TYPE=x11 diff --git a/docs/deploy-usage.md b/docs/deploy-usage.md index c656e2c9..2f2aad76 100644 --- a/docs/deploy-usage.md +++ b/docs/deploy-usage.md @@ -11,7 +11,7 @@ Environment variables are used to configure the Helios container. The following | GID | POSIX compliant gid for the user | | | PASSWORD | Password set for the user. Required for DCV native client direct-connect (port 8443) | | | IDLE_TIME | Trigger the idle hook after x minutes. Previously used by the [auto shutdown plugin](plugins-autoshutdown.md), which is deprecated as of Genesis `v5.2.0` / Orion Workspaces `v4.3.0` in favor of Orion's built-in auto shutdown / auto hibernate | | -| DISABLE_VGL | Disable VirtualGL Wrapper around the entire desktop session. Set to `false` to use vglrun (default: `true`, vglrun disabled). Set to `true` (or any value) to run without vglrun. Matches the pattern of DISABLE_ZINK. | | +| DISABLE_VGL | Disable VirtualGL Wrapper around the entire desktop session. Set to `false` to use vglrun (default: `false`, vglrun enabled). Set to `true` (or any value) to run without vglrun. Matches the pattern of DISABLE_ZINK. | | | DISABLE_ZINK | Disable ZINK acceleration. Set to `false` to enable ZINK (default: `true`, ZINK disabled). Set to `true` (or any value) to disable ZINK. Matches the pattern of DISABLE_VGL. | | | DESKTOP_FILES | Paths separated by `:`. For example, `/some/path/1/*.desktop:/some/*/2/*.desktop` | | | PREFIX | Prefix for URL for use behind a reverse proxy, both slashes required, e.g. `/custom/prefix/` | | @@ -22,8 +22,88 @@ Environment variables are used to configure the Helios container. The following | DCV_DIRECT_PORT | Port for the DCV native client direct-connect endpoint. Default `8443`. Requires `PASSWORD` to be set. | | -When using the Orion Platform, you can configure them in the [Templates](https://juno-fx.github.io/Orion-Documentation/genesis/workstations/) -User-related settings are already configured automatically by the platform. The Templates are there to adjust settings such as your framerate. +## GPU Acceleration Configuration + +### Running Without a GPU +Helios can be run without a physical GPU. The default configuration has `DISABLE_VGL=false` (vglrun enabled), which allows the desktop to start via VirtualGL's software rendering path (llvpipe). This is the out-of-the-box experience for cloud/deployments without GPU hardware. If you have no GPU and experience issues, verify your container has access to `/dev/dri` devices. + +### Running With ZINK +Set `DISABLE_ZINK=false` to enable ZINK acceleration. ZINK is an OpenGL implementation that runs over Vulkan and is particularly useful: +- **AMD GPUs** with open-source drivers that support Vulkan but have limited native OpenGL support +- **Compatibility scenarios** where applications expect OpenGL but the backend is Vulkan-based +- **Container environments** where direct driver access is restricted + +Note that ZINK may add overhead for some workloads. The default is `DISABLE_ZINK=true` (ZINK disabled). + +### 3D Heavy Applications (Houdini, Maya, etc.) +For professional 3D applications with a discrete GPU, you may experience performance issues if VGL or ZINK are enabled. Both add translation overhead: +- **VGL** adds host-side VirtualGL translation +- **ZINK** adds OpenGL-to-Vulkan translation + +For best performance with Houdini, Maya, or similar applications: +1. Set `DISABLE_VGL=true` to disable the VGL wrapper +2. Set `DISABLE_ZINK=true` to disable ZINK acceleration + +When disabling both features and using native GPU drivers, you will also need to proper ICD (Installable Client Driver) files so OpenGL can discover the correct GPU driver (see "ICD Files for Target GPU" below). + +### ICD Files for Target GPU +When using native GPU drivers (both VGL and ZINK disabled), you need to provide ICD (Installable Client Driver) configuration so the OpenGL stack can find the correct driver library. + +**NVIDIA ICD example** (`nvidia.json`): +```json +{ + "file_format_version" : "1.0.0", + "ICD" : { + "library_path" : "libGLX_nvidia.so.0" + } +} +``` + +**ICD file placement:** +- `/etc/ld.so.d/` — for library linker discovery (example above) +- `/usr/share/glvnd/egl/vendor.d/` — preferred for modern GLVND implementations + +**Deployment method examples:** + +**Docker run:** +```bash +docker run -v /path/to/nvidia.json:/etc/ld.so.d/nvidia.json \ + -e DISABLE_VGL=true -e DISABLE_ZINK=true \ + junoinnovations/helios:unstable-jammy +``` + +**Docker Compose:** +```yaml +services: + helios: + image: junoinnovations/helios:unstable-jammy + volumes: + - ./nvidia.json:/etc/ld.so.d/nvidia.json + environment: + - DISABLE_VGL=true + - DISABLE_ZINK=true +``` + +**Kubernetes:** +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: helios +spec: + template: + spec: + containers: + - name: helios + image: junoinnovations/helios:unstable-jammy + volumeMounts: + - name: nvidia-icd + mountPath: /etc/ld.so.d + volumes: + - name: nvidia-icd + configMap: + name: nvidia-icd-config +``` When using `REMOTE_PROTOCOL=selkies` (the default), many of the environment variables provided by the upstream Selkies project will be respected. You can find official Selkies documentation here: https://selkies-project.github.io/selkies/usage/#command-line-options-and-environment-variables