aldmbmtl · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026
diff --git 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)   |
+| `<host>:<DCV_DIRECT_PORT>`      | 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 `<host>:<DCV_DIRECT_PORT>` and username `<USER>`.
+
+## 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 <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)   |
-| `<host>:<DCV_DIRECT_PORT>`      | 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 `<host>:<DCV_DIRECT_PORT>` and username `<USER>`.
-
-## 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 <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`).