From feb6c0863b4e5169ee22ef6b8b667470e2e3a332 Mon Sep 17 00:00:00 2001 From: "juno-ci[bot]" <216071710+juno-ci[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 14:47:11 -0500 Subject: [PATCH 1/2] 201-doc-formatting (#202) * pr commit * Updated docs --------- Co-authored-by: app/github-actions Co-authored-by: aldmbmtl --- docs/deploy-usage.md | 214 ++++++++++++++++++++++--------------------- 1 file changed, 112 insertions(+), 102 deletions(-) diff --git a/docs/deploy-usage.md b/docs/deploy-usage.md index 2f2aad7..ce7983b 100644 --- a/docs/deploy-usage.md +++ b/docs/deploy-usage.md @@ -21,6 +21,106 @@ Environment variables are used to configure the Helios container. The following | DCV_LICENSE_FILE | Path to a DCV license file for non-EC2 usage. Falls back to auto-license on EC2 or 30-day demo otherwise. | | | DCV_DIRECT_PORT | Port for the DCV native client direct-connect endpoint. Default `8443`. Requires `PASSWORD` to be set. | | +## Endpoints + +Helios provides the following endpoints for accessing the desktop: + +### Selkies mode (`REMOTE_PROTOCOL=selkies`) + +| Endpoint | Description | +|-----------------------|-------------------------------| +| `{PREFIX}/` | Web-based desktop (port 3000) | + +### DCV mode (`REMOTE_PROTOCOL=dcv`) + +| Endpoint | Description | +|---------------------------------|------------------------------------------------------| +| `{PREFIX}/` | Web-based desktop via browser (port 3000, no auth) | +| `:` | Native DCV client direct-connect (port 8443, PAM auth via `PASSWORD`) | + +The DCV direct-connect endpoint uses both TCP and QUIC (UDP) for lower-latency streaming. +Connect using the [DCV native client](https://docs.aws.amazon.com/dcv/latest/adminguide/client.html) +with the address `:` and username ``. + +## Ports + +Helios exposes the following ports: + +| Port | Protocol | Description | +|------|----------|--------------------------------| +| 3000 | TCP | HTTPS Desktop (Selkies or DCV) | +| 8443 | TCP+UDP | DCV native client direct-connect (when `REMOTE_PROTOCOL=dcv` and `PASSWORD` is set) | + +## Remote Protocols + +### Selkies (default) + +Selkies is a WebRTC-based remote desktop protocol. It provides a web-based client that works +in any modern browser without additional software. Selkies is the default and recommended +protocol for browser-based access. + +### DCV + +[Amazon DCV (NICE DCV)](https://aws.amazon.com/hpc/dcv/) is an alternative remote desktop +protocol that supports both web browser and native client access. + +DCV key characteristics: + +- **Console sessions only** — DCV connects to the same Xvfb display as Selkies. Both + protocols show the same desktop. +- **Web access** — Served on port 3000 behind nginx, same as Selkies. The web endpoint + is unauthenticated. +- **Native client** — A separate dcvserver instance on port 8443 provides + password-authenticated access for the [DCV native client](https://docs.aws.amazon.com/dcv/latest/adminguide/client.html). + Requires `PASSWORD` to be set. +- **iframe embedding** — DCV web client supports iframe embedding from any origin (CORS + headers are set, `X-Frame-Options` is stripped). +- **No GPU sharing** — DCV-GL is installed but the console session does not use it. + GPU acceleration is handled by VirtualGL (same as Selkies). + +!!! info "DCV Licensing" + + DCV requires a license. Helios handles licensing automatically: + + - **On EC2** uses the free built-in EC2 license. + - **Without a license** starts a 30-day demo license on first run. + - **BYOL** set `DCV_LICENSE_FILE` to the path of your license file. + + The demo license is generated at container start via the DCV package postinst + script. This ensures each container gets its own valid license state. + +!!! warning "EC2 IMDS Hop Limit" + + On EC2, DCV fetches its free license from the Instance Metadata Service + (IMDS) at `169.254.169.254`. Containers in a separate network namespace + (bridge/overlay) add one extra hop. The default IMDS hop limit of `1` + drops their requests, causing DCV license checkout to fail. + + **Host networking** (`--network host`) — no extra hop. Default hop limit + works. No change needed. + + - **Bridge/overlay/EKS/Fargate** — IMDS needs hop limit ≥ 2: + + - **Karpenter** — add to `EC2NodeClass.spec.metadataOptions`: + ```yaml + httpPutResponseHopLimit: 2 + ``` + - **EKS managed node groups / launch templates** — set + `MetadataOptions.HttpPutResponseHopLimit` to `2`. + - **Plain Docker / ECS EC2** — apply to the instance: + ```bash + aws ec2 modify-instance-metadata-options \ + --instance-id \ + --http-put-response-hop-limit 2 + ``` + +!!! info "DCV Audio" + + DCV uses the same PulseAudio null-sink setup as Selkies. Desktop audio is captured + from the output monitor and streamed to the client. Microphone input arrives via + the DCV agent's virtual microphone (`AWS-Virtual-Microphone`). + + ## GPU Acceleration Configuration @@ -29,18 +129,26 @@ Helios can be run without a physical GPU. The default configuration has `DISABLE ### 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). +!!! warning + + 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 professional 3D applications with a discrete GPU, you may experience performance issues if VGL or ZINK are enabled. +Both add translation overhead: + +!!! warning + + - **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 @@ -137,101 +245,3 @@ You can find official Selkies documentation here: https://selkies-project.github When using the [Orion Platform](https://juno-fx.github.io/Orion-Documentation/), Authentication and authorization is handled by the product, ensuring the security of your deployment. -## Endpoints - -Helios provides the following endpoints for accessing the desktop: - -### Selkies mode (`REMOTE_PROTOCOL=selkies`) - -| Endpoint | Description | -|-----------------------|-------------------------------| -| `{PREFIX}/` | Web-based desktop (port 3000) | - -### DCV mode (`REMOTE_PROTOCOL=dcv`) - -| Endpoint | Description | -|---------------------------------|------------------------------------------------------| -| `{PREFIX}/` | Web-based desktop via browser (port 3000, no auth) | -| `:` | Native DCV client direct-connect (port 8443, PAM auth via `PASSWORD`) | - -The DCV direct-connect endpoint uses both TCP and QUIC (UDP) for lower-latency streaming. -Connect using the [DCV native client](https://docs.aws.amazon.com/dcv/latest/adminguide/client.html) -with the address `:` and username ``. - -## Ports - -Helios exposes the following ports: - -| Port | Protocol | Description | -|------|----------|--------------------------------| -| 3000 | TCP | HTTPS Desktop (Selkies or DCV) | -| 8443 | TCP+UDP | DCV native client direct-connect (when `REMOTE_PROTOCOL=dcv` and `PASSWORD` is set) | - -## Remote Protocols - -### Selkies (default) - -Selkies is a WebRTC-based remote desktop protocol. It provides a web-based client that works -in any modern browser without additional software. Selkies is the default and recommended -protocol for browser-based access. - -### DCV - -[Amazon DCV (NICE DCV)](https://aws.amazon.com/hpc/dcv/) is an alternative remote desktop -protocol that supports both web browser and native client access. - -DCV key characteristics: - -- **Console sessions only** — DCV connects to the same Xvfb display as Selkies. Both - protocols show the same desktop. -- **Web access** — Served on port 3000 behind nginx, same as Selkies. The web endpoint - is unauthenticated. -- **Native client** — A separate dcvserver instance on port 8443 provides - password-authenticated access for the [DCV native client](https://docs.aws.amazon.com/dcv/latest/adminguide/client.html). - Requires `PASSWORD` to be set. -- **iframe embedding** — DCV web client supports iframe embedding from any origin (CORS - headers are set, `X-Frame-Options` is stripped). -- **No GPU sharing** — DCV-GL is installed but the console session does not use it. - GPU acceleration is handled by VirtualGL (same as Selkies). - -!!! info "DCV Licensing" - - DCV requires a license. Helios handles licensing automatically: - - - **On EC2** uses the free built-in EC2 license. - - **Without a license** starts a 30-day demo license on first run. - - **BYOL** set `DCV_LICENSE_FILE` to the path of your license file. - - The demo license is generated at container start via the DCV package postinst - script. This ensures each container gets its own valid license state. - -!!! warning "EC2 IMDS Hop Limit" - - On EC2, DCV fetches its free license from the Instance Metadata Service - (IMDS) at `169.254.169.254`. Containers in a separate network namespace - (bridge/overlay) add one extra hop. The default IMDS hop limit of `1` - drops their requests, causing DCV license checkout to fail. - - **Host networking** (`--network host`) — no extra hop. Default hop limit - works. No change needed. - - - **Bridge/overlay/EKS/Fargate** — IMDS needs hop limit ≥ 2: - - - **Karpenter** — add to `EC2NodeClass.spec.metadataOptions`: - ```yaml - httpPutResponseHopLimit: 2 - ``` - - **EKS managed node groups / launch templates** — set - `MetadataOptions.HttpPutResponseHopLimit` to `2`. - - **Plain Docker / ECS EC2** — apply to the instance: - ```bash - aws ec2 modify-instance-metadata-options \ - --instance-id \ - --http-put-response-hop-limit 2 - ``` - -!!! info "DCV Audio" - - DCV uses the same PulseAudio null-sink setup as Selkies. Desktop audio is captured - from the output monitor and streamed to the client. Microphone input arrives via - the DCV agent's virtual microphone (`AWS-Virtual-Microphone`). From c424f0a75bd81f0dfda43a571d75a13abf1a3532 Mon Sep 17 00:00:00 2001 From: app/github-actions Date: Mon, 2 Nov 2026 19:47:53 +0000 Subject: [PATCH 2/2] pr commit