Skip to content

Commit 74eb38a

Browse files
LinuxServer-CILinuxServer-CI
committed
Bot Updating Templated Files
1 parent f99b314 commit 74eb38a

File tree

1 file changed

+101
-87
lines changed

1 file changed

+101
-87
lines changed

‎README.md‎

Lines changed: 101 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,61 @@ The web interface includes a terminal with passwordless `sudo` access. Any user
8080

8181
While not generally recommended, certain legacy environments specifically those with older hardware or outdated Linux distributions may require the deactivation of the standard seccomp profile to get containerized desktop software to run. This can be achieved by utilizing the `--security-opt seccomp=unconfined` parameter. It is critical to use this option only when absolutely necessary as it disables a key security layer of Docker, elevating the potential for container escape vulnerabilities.
8282

83+
### Hardware Acceleration & The Move to Wayland
84+
85+
We are currently transitioning our desktop containers from X11 to Wayland. While X11 is still the default, we strongly encourage users to test the new Wayland mode.
86+
87+
**Important:** GPU acceleration support for X11 is being deprecated. Future development for hardware acceleration will focus entirely on the Wayland stack.
88+
89+
To enable Wayland mode, set the following environment variable:
90+
* `-e PIXELFLUX_WAYLAND=true`
91+
92+
**Why use Wayland?**
93+
* **Zero Copy Encoding:** When configured correctly with a GPU, the frame is rendered and encoded on the video card without ever being copied to the system RAM. This drastically lowers CPU usage and latency.
94+
* **Modern Stack:** Single-application containers utilize **Labwc** (replacing Openbox) and full desktop containers use **KDE Plasma Wayland**, providing a more modern and secure compositing environment while retaining the same user experience.
95+
96+
#### GPU Configuration
97+
98+
To use hardware acceleration in Wayland mode, we distinguish between the card used for **Rendering** (3D apps/Desktops) and **Encoding** (Video Stream).
99+
100+
**Configuration Variables:**
101+
* `DRINODE`: The path to the GPU used for **Rendering** (EGL).
102+
* `DRI_NODE`: The path to the GPU used for **Encoding** (VAAPI/NVENC).
103+
104+
If both variables point to the same device, the container will automatically enable **Zero Copy** encoding, significantly reducing CPU usage and latency.
105+
106+
##### Intel & AMD (Open Source Drivers)
107+
108+
For Intel and AMD GPUs.
109+
110+
```yaml
111+
devices:
112+
- /dev/dri:/dev/dri
113+
environment:
114+
- PIXELFLUX_WAYLAND=true
115+
# Optional: Specify device if multiple exist (IE: /dev/dri/renderD129)
116+
- DRINODE=/dev/dri/renderD128
117+
- DRI_NODE=/dev/dri/renderD128
118+
```
119+
120+
121+
### SealSkin Compatibility
122+
123+
This container is compatible with [SealSkin](https://sealskin.app).
124+
125+
SealSkin is a self-hosted, client-server platform that provides secure authentication and collaboration features while using a browser extension to intercept user actions such as clicking a link or downloading a file and redirect them to a secure, isolated application environment running on a remote server.
126+
127+
* **SealSkin Server:** [Get it Here](https://github.com/linuxserver/docker-sealskin)
128+
* **Browser Extension:** [Chrome](https://chromewebstore.google.com/detail/sealskin-isolation/lclgfmnljgacfdpmmmjmfpdelndbbfhk) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/sealskin-isolation/).
129+
* **Mobile App:** [iOS](https://apps.apple.com/us/app/sealskin/id6758210210) and [Android](https://play.google.com/store/apps/details?id=io.linuxserver.sealskin)
130+
131+
83132
### Options in all Selkies-based GUI containers
84133
85-
This container is based on [Docker Baseimage Selkies](https://github.com/linuxserver/docker-baseimage-selkies), which provides the following environment variables and run configurations to customize its functionality.
134+
This container is based on [Docker Baseimage Selkies](https://github.com/linuxserver/docker-baseimage-selkies).
86135
87-
#### Optional Environment Variables
136+
<details>
137+
<summary>Click to expand: Optional Environment Variables</summary>
88138
89139
| Variable | Description |
90140
| :----: | --- |
@@ -93,8 +143,8 @@ This container is based on [Docker Baseimage Selkies](https://github.com/linuxse
93143
| CUSTOM_HTTPS_PORT | Internal port the container listens on for https if it needs to be swapped from the default `3001` |
94144
| CUSTOM_WS_PORT | Internal port the container listens on for websockets if it needs to be swapped from the default 8082 |
95145
| CUSTOM_USER | HTTP Basic auth username, abc is default. |
96-
| DRI_NODE | Enable VAAPI stream encoding and use the specified device IE `/dev/dri/renderD128` |
97-
| DRINODE | Specify which GPU to use for DRI3 acceleration IE `/dev/dri/renderD129` |
146+
| DRI_NODE | **Encoding GPU**: Enable VAAPI/NVENC stream encoding and use the specified device IE `/dev/dri/renderD128` |
147+
| DRINODE | **Rendering GPU**: Specify which GPU to use for EGL/3D acceleration IE `/dev/dri/renderD129` |
98148
| PASSWORD | HTTP Basic auth password, abc is default. If unset there will be no auth |
99149
| SUBFOLDER | Subfolder for the application if running a subfolder reverse proxy, need both slashes IE `/subfolder/` |
100150
| TITLE | The page title displayed on the web browser, default "Selkies" |
@@ -120,70 +170,52 @@ This container is based on [Docker Baseimage Selkies](https://github.com/linuxse
120170
- **5**: Centered
121171
- **6**: Animated
122172

123-
#### Optional Run Configurations
173+
</details>
174+
175+
<details>
176+
<summary>Click to expand: Optional Run Configurations (DinD & GPU Mounts)</summary>
124177

125178
| Argument | Description |
126179
| :----: | --- |
127180
| `--privileged` | Starts a Docker-in-Docker (DinD) environment. For better performance, mount the Docker data directory from the host, e.g., `-v /path/to/docker-data:/var/lib/docker`. |
128181
| `-v /var/run/docker.sock:/var/run/docker.sock` | Mounts the host's Docker socket to manage host containers from within this container. |
129-
| `--device /dev/dri:/dev/dri` | Mount a GPU into the container, this can be used in conjunction with the `DRINODE` environment variable to leverage a host video card for GPU accelerated applications. Only **Open Source** drivers are supported IE (Intel,AMDGPU,Radeon,ATI,Nouveau) |
130-
131-
### Language Support - Internationalization
132-
133-
To launch the desktop session in a different language, set the `LC_ALL` environment variable. For example:
134-
135-
* `-e LC_ALL=zh_CN.UTF-8` - Chinese
136-
* `-e LC_ALL=ja_JP.UTF-8` - Japanese
137-
* `-e LC_ALL=ko_KR.UTF-8` - Korean
138-
* `-e LC_ALL=ar_AE.UTF-8` - Arabic
139-
* `-e LC_ALL=ru_RU.UTF-8` - Russian
140-
* `-e LC_ALL=es_MX.UTF-8` - Spanish (Latin America)
141-
* `-e LC_ALL=de_DE.UTF-8` - German
142-
* `-e LC_ALL=fr_FR.UTF-8` - French
143-
* `-e LC_ALL=nl_NL.UTF-8` - Netherlands
144-
* `-e LC_ALL=it_IT.UTF-8` - Italian
145-
146-
### SealSkin Compatibility
182+
| `--device /dev/dri:/dev/dri` | Mount a GPU into the container, this can be used in conjunction with the `DRINODE` environment variable to leverage a host video card for GPU accelerated applications. |
147183

148-
This container is compatible with [SealSkin](https://github.com/linuxserver/docker-sealskin).
149-
150-
SealSkin is a self-hosted, client-server platform that provides secure authentication and collaboration features while using a browser extension to intercept user actions such as clicking a link or downloading a file and redirect them to a secure, isolated application environment running on a remote server.
184+
</details>
151185

152-
* **SealSkin Server:** [Get it Here](https://github.com/linuxserver/docker-sealskin)
153-
* **Browser Extension:** [Install Here](https://chromewebstore.google.com/detail/sealskin-isolation/lclgfmnljgacfdpmmmjmfpdelndbbfhk)
186+
<details>
187+
<summary>Click to expand: Legacy X11 Resolution & Acceleration</summary>
154188

155-
### All GPU Acceleration - use sane resolutions
189+
**Note:** This section applies only if you are **NOT** using `PIXELFLUX_WAYLAND=true`.
156190

157-
When using 3d acceleration via Nvidia DRM or DRI3 it is important to clamp the virtual display to a reasonable max resolution. This can be achieved with the environment setting:
191+
When using 3d acceleration via Nvidia DRM or DRI3 in X11 mode, it is important to clamp the virtual display to a reasonable max resolution to avoid memory exhaustion or poor performance.
158192

159193
* `-e MAX_RESOLUTION=3840x2160`
160194

161-
This will set the total virtual framebuffer to 4K, you can also set a manual resolution to achieve this.
162-
By default the virtual monitor in the session is 16K to support large monitors and dual display configurations. Leaving it this large has no impact on CPU based performance but costs GPU memory usage and memory bandwidth when leveraging one for acceleration. If you have performance issues in an accelerated session, try clamping the resolution to 1080p and work up from there:
195+
This will set the total virtual framebuffer to 4K. By default, the virtual monitor is 16K. If you have performance issues in an accelerated X11 session, try clamping the resolution to 1080p and work up from there:
163196

164197
```
165198
-e SELKIES_MANUAL_WIDTH=1920
166199
-e SELKIES_MANUAL_HEIGHT=1080
167200
-e MAX_RESOLUTION=1920x1080
168201
```
169202

170-
### DRI3 GPU Acceleration
171-
172-
For accelerated apps or games, render devices can be mounted into the container and leveraged by applications using:
173-
174-
`--device /dev/dri:/dev/dri`
203+
</details>
175204

176-
This feature only supports **Open Source** GPU drivers:
177-
178-
| Driver | Description |
179-
| :----: | --- |
180-
| Intel | i965 and i915 drivers for Intel iGPU chipsets |
181-
| AMD | AMDGPU, Radeon, and ATI drivers for AMD dedicated or APU chipsets |
182-
| NVIDIA | nouveau2 drivers only, closed source NVIDIA drivers lack DRI3 support |
205+
### Language Support - Internationalization
183206

184-
The `DRINODE` environment variable can be used to point to a specific GPU.
207+
To launch the desktop session in a different language, set the `LC_ALL` environment variable. For example:
185208

186-
DRI3 will work on aarch64 given the correct drivers are installed inside the container for your chipset.
209+
* `-e LC_ALL=zh_CN.UTF-8` - Chinese
210+
* `-e LC_ALL=ja_JP.UTF-8` - Japanese
211+
* `-e LC_ALL=ko_KR.UTF-8` - Korean
212+
* `-e LC_ALL=ar_AE.UTF-8` - Arabic
213+
* `-e LC_ALL=ru_RU.UTF-8` - Russian
214+
* `-e LC_ALL=es_MX.UTF-8` - Spanish (Latin America)
215+
* `-e LC_ALL=de_DE.UTF-8` - German
216+
* `-e LC_ALL=fr_FR.UTF-8` - French
217+
* `-e LC_ALL=nl_NL.UTF-8` - Netherlands
218+
* `-e LC_ALL=it_IT.UTF-8` - Italian
187219

188220
### Application Management
189221

@@ -211,20 +243,19 @@ You can install packages from the system's native repository using the [universa
211243
- INSTALL_PACKAGES=libfuse2|git|gdb
212244
```
213245

214-
#### Hardening
246+
### Advanced Configuration
215247

216-
These variables can be used to lock down the desktop environment for single-application use cases or to restrict user capabilities.
248+
<details>
249+
<summary>Click to expand: Hardening Options</summary>
217250

218-
##### Meta Variables
219-
220-
These variables act as presets, enabling multiple hardening options at once. Individual options can still be set to override the preset.
251+
These variables can be used to lock down the desktop environment for single-application use cases or to restrict user capabilities.
221252

222253
| Variable | Description |
223254
| :----: | --- |
224255
| **`HARDEN_DESKTOP`** | Enables `DISABLE_OPEN_TOOLS`, `DISABLE_SUDO`, and `DISABLE_TERMINALS`. Also sets related Selkies UI settings (`SELKIES_FILE_TRANSFERS`, `SELKIES_COMMAND_ENABLED`, `SELKIES_UI_SIDEBAR_SHOW_FILES`, `SELKIES_UI_SIDEBAR_SHOW_APPS`) if they are not explicitly set by the user. |
225256
| **`HARDEN_OPENBOX`** | Enables `DISABLE_CLOSE_BUTTON`, `DISABLE_MOUSE_BUTTONS`, and `HARDEN_KEYBINDS`. It also flags `RESTART_APP` if not set by the user, ensuring the primary application is automatically restarted if closed. |
226257

227-
##### Individual Hardening Variables
258+
**Individual Hardening Variables:**
228259

229260
| Variable | Description |
230261
| :--- | --- |
@@ -236,46 +267,27 @@ These variables act as presets, enabling multiple hardening options at once. Ind
236267
| **`HARDEN_KEYBINDS`** | If true, disables default Openbox keybinds that can bypass other hardening options (e.g., `Alt+F4` to close windows, `Alt+Escape` to show the root menu). |
237268
| **`RESTART_APP`** | If true, enables a watchdog service that automatically restarts the main application if it is closed. The user's autostart script is made read-only and root owned to prevent tampering. |
238269

239-
#### Selkies application settings
270+
</details>
240271

241-
Using environment variables every facet of the application can be configured.
242-
243-
##### Booleans and Locking
244-
Boolean settings accept `true` or `false`. You can also prevent the user from changing a boolean setting in the UI by appending `|locked`. The UI toggle for this setting will be hidden.
245-
246-
* **Example**: To force CPU encoding on and prevent the user from disabling it:
247-
```bash
248-
-e SELKIES_USE_CPU="true|locked"
249-
```
272+
<details>
273+
<summary>Click to expand: Selkies Application Settings</summary>
250274

251-
##### Enums and Lists
252-
These settings accept a comma-separated list of values. Their behavior depends on the number of items provided:
253-
254-
* **Multiple Values**: The first item in the list becomes the default selection, and all items in the list become the available options in the UI dropdown.
255-
* **Single Value**: The provided value becomes the default, and the UI dropdown is hidden because the choice is locked.
256-
257-
* **Example**: Force the encoder to be `jpeg` with no other options available to the user:
258-
```bash
259-
-e SELKIES_ENCODER="jpeg"
260-
```
261-
262-
##### Ranges
263-
Range settings define a minimum and maximum for a value (e.g., framerate).
275+
Using environment variables every facet of the application can be configured.
264276

265-
* **To set a range**: Use a hyphen-separated `min-max` format. The UI will show a slider.
266-
* **To set a fixed value**: Provide a single number. This will lock the value and hide the UI slider.
277+
**Booleans and Locking:**
278+
Boolean settings accept `true` or `false`. You can also prevent the user from changing a boolean setting in the UI by appending `|locked`.
279+
* Example: `-e SELKIES_USE_CPU="true|locked"`
267280

268-
* **Example**: Lock the framerate to exactly 60 FPS.
269-
```bash
270-
-e SELKIES_FRAMERATE="60"
271-
```
281+
**Enums and Lists:**
282+
These settings accept a comma-separated list of values. The first item becomes default. If only one item is provided, the UI dropdown is hidden.
283+
* Example: `-e SELKIES_ENCODER="jpeg"`
272284

273-
##### Manual Resolution Mode
274-
The server can be forced to use a single, fixed resolution for all connecting clients. This mode is automatically activated if `SELKIES_MANUAL_WIDTH`, `SELKIES_MANUAL_HEIGHT`, or `SELKIES_IS_MANUAL_RESOLUTION_MODE` is set.
285+
**Ranges:**
286+
Use a hyphen-separated `min-max` format for a slider, or a single number to lock the value.
287+
* Example: `-e SELKIES_FRAMERATE="60"`
275288

276-
* If `SELKIES_MANUAL_WIDTH` and/or `SELKIES_MANUAL_HEIGHT` are set, the resolution is locked to those values.
277-
* If `SELKIES_IS_MANUAL_RESOLUTION_MODE` is set to `true` without specifying width or height, the resolution defaults to **1024x768**.
278-
* When this mode is active, the client UI for changing resolution is disabled.
289+
**Manual Resolution Mode:**
290+
If `SELKIES_MANUAL_WIDTH` or `SELKIES_MANUAL_HEIGHT` are set, the resolution is locked to those values.
279291

280292
| Environment Variable | Default Value | Description |
281293
| --- | --- | --- |
@@ -336,12 +348,14 @@ The server can be forced to use a single, fixed resolution for all connecting cl
336348
| `SELKIES_ENABLE_PLAYER3` | `True` | Enable sharing link for gamepad player 3. |
337349
| `SELKIES_ENABLE_PLAYER4` | `True` | Enable sharing link for gamepad player 4. |
338350

351+
</details>
352+
339353
## Usage
340354

341355
To help you get started creating a container from this image you can either use docker-compose or the docker cli.
342356

343357
>[!NOTE]
344-
>Unless a parameter is flaged as 'optional', it is *mandatory* and a value must be provided.
358+
>Unless a parameter is flagged as 'optional', it is *mandatory* and a value must be provided.
345359

346360
### docker-compose (recommended, [click here for more info](https://docs.linuxserver.io/general/docker-compose))
347361

0 commit comments

Comments
 (0)