Selkies Base Images from LinuxServer

The purpose of these images is to provide a full featured web native Linux desktop experience for any Linux application or desktop environment. These images replace our old base images at KasmVNC for greatly increased performance, fidelity, and feature set. They ship with passwordless sudo to allow easy package installation, testing, and customization. By default they have no logic to mount out anything but the users home directory, meaning on image updates anything outside of /config will be lost.

• Support for using our base images in your own projects is provided on a Reasonable Endeavours basis, please see our Support Policy for details.
• There is no latest tag for any of our base images, by design. We often make breaking changes between versions, and we don't publish release notes like we do for the downstream images.
• If you're intending to distribute an image using one of our bases, please read our docs on container branding first.
• Images are supported for as long as the upstream release on which they are based, after which we will stop building new base images for that version.

These images contain the following services:

• Selkies - The core technology for interacting with a containerized desktop from a web browser.
• pixelflux - The core video/image rendering pipeline.
• pcmflux - Lean low level web native opus audio encoder.
• NGINX - Used to serve Selkies with the appropriate paths and provide basic auth.
• Docker - Can be used for interacting with a mounted in Docker socket or if the container is run in privileged mode will start a DinD setup.
• PulseAudio - Sound subsystem used to capture audio from the active desktop session and send it to the browser.

Options

Authentication for these containers is included as a convenience and to keep in sync with the previous KasmVNC containers they replace. We use bash to substitute in settings user/password and some strings might break that. In general this authentication mechanism should be used to keep the kids out not the internet

If you are looking for a robust secure application gateway please check out SWAG.

All application settings are passed via environment variables:

Variable	Description
CUSTOM_PORT	Internal port the container listens on for http if it needs to be swapped from the default 3000.
CUSTOM_HTTPS_PORT	Internal port the container listens on for https if it needs to be swapped from the default 3001.
CUSTOM_WS_PORT	Internal port the container listens on for websockets if it needs to be swapped from the default 8082.
CUSTOM_USER	HTTP Basic auth username, abc is default.
PASSWORD	HTTP Basic auth password, abc is default. If unset there will be no auth
SUBFOLDER	Subfolder for the application if running a subfolder reverse proxy, need both slashes IE /subfolder/
TITLE	The page title displayed on the web browser, default "Selkies - webrtc".
START_DOCKER	If set to false a container with privilege will not automatically start the DinD Docker setup.
DISABLE_IPV6	If set to true or any value this will disable IPv6
LC_ALL	Set the Language for the container to run as IE fr_FR.UTF-8 ar_AE.UTF-8
NO_DECOR	If set the application will run without window borders for use as a PWA. (Decor can be enabled and disabled with Ctrl+Shift+d)
NO_FULL	Do not autmatically fullscreen applications when using openbox.
DISABLE_ZINK	Do not set the Zink environment variables if a video card is detected (userspace applications will use CPU rendering)
WATERMARK_PNG	Full path inside the container to a watermark png IE /usr/share/selkies/www/icon.png
WATERMARK_LOCATION	Where to paint the image over the stream integer options below
MAX_RES	Pass a larger maximum resolution for the container default is 16k 15360x8640

• 1 - Top Left
• 2 - Top Right
• 3 - Bottom Left
• 4 - Bottom Right
• 5 - Centered
• 6 - Animated

Selkies application settings

Using environment variables every facet of the application can be configured.

Setting Types and UI Customization

Certain setting types have special syntax for advanced control over the client-side UI and available options. A key concept is that any setting that is locked to a single value will not be rendered in the UI, giving the user no option to change it. This, combined with the various ui_ visibility settings, allows administrators to completely customize the client interface.

Booleans and Locking

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.

• Example: To force CPU encoding on and prevent the user from disabling it:

  -e SELKIES_USE_CPU="true|locked"

Enums and Lists

These settings accept a comma-separated list of values. Their behavior depends on the number of items provided:

• 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.

• Single Value: The provided value becomes the default, and the UI dropdown is hidden because the choice is locked.

• Example: Force the encoder to be jpeg with no other options available to the user:

  -e SELKIES_ENCODER="jpeg"

Ranges

Range settings define a minimum and maximum for a value (e.g., framerate).

• To set a range: Use a hyphen-separated min-max format. The UI will show a slider.

• To set a fixed value: Provide a single number. This will lock the value and hide the UI slider.

• Example: Lock the framerate to exactly 60 FPS.

  -e SELKIES_FRAMERATE="60"

Manual Resolution Mode

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.

• If SELKIES_MANUAL_WIDTH and/or SELKIES_MANUAL_HEIGHT are set, the resolution is locked to those values.
• If SELKIES_IS_MANUAL_RESOLUTION_MODE is set to true without specifying width or height, the resolution defaults to 1024x768.
• When this mode is active, the client UI for changing resolution is disabled.

Environment Variable	Default Value	Description
SELKIES_UI_TITLE	'Selkies'	Title in top left corner of sidebar.
SELKIES_UI_SHOW_LOGO	True	Show the Selkies logo in the sidebar.
SELKIES_UI_SHOW_SIDEBAR	True	Show the main sidebar UI.
SELKIES_UI_SHOW_CORE_BUTTONS	True	Show the core components buttons display, audio, microphone, and gamepad.
SELKIES_UI_SIDEBAR_SHOW_VIDEO_SETTINGS	True	Show the video settings section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_SCREEN_SETTINGS	True	Show the screen settings section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_AUDIO_SETTINGS	True	Show the audio settings section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_STATS	True	Show the stats section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_CLIPBOARD	True	Show the clipboard section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_FILES	True	Show the file transfer section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_APPS	True	Show the applications section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_SHARING	True	Show the sharing section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_GAMEPADS	True	Show the gamepads section in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_FULLSCREEN	True	Show the fullscreen button in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_GAMING_MODE	True	Show the gaming mode button in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_TRACKPAD	True	Show the virtual trackpad button in the sidebar.
SELKIES_UI_SIDEBAR_SHOW_KEYBOARD_BUTTON	True	Show the on-screen keyboard button in the display area.
SELKIES_UI_SIDEBAR_SHOW_SOFT_BUTTONS	True	Show the soft buttons section in the sidebar.
SELKIES_AUDIO_ENABLED	True	Enable server-to-client audio streaming.
SELKIES_MICROPHONE_ENABLED	True	Enable client-to-server microphone forwarding.
SELKIES_GAMEPAD_ENABLED	True	Enable gamepad support.
SELKIES_CLIPBOARD_ENABLED	True	Enable clipboard synchronization.
SELKIES_COMMAND_ENABLED	True	Enable parsing of command websocket messages.
SELKIES_FILE_TRANSFERS	'upload,download'	Allowed file transfer directions (comma-separated: "upload,download"). Set to "" or "none" to disable.
SELKIES_ENCODER	'x264enc,x264enc-striped,jpeg'	The default video encoders.
SELKIES_FRAMERATE	'8-120'	Allowed framerate range or a fixed value.
SELKIES_H264_CRF	'5-50'	Allowed H.264 CRF range or a fixed value.
SELKIES_JPEG_QUALITY	'1-100'	Allowed JPEG quality range or a fixed value.
SELKIES_H264_FULLCOLOR	False	Enable H.264 full color range for pixelflux encoders.
SELKIES_H264_STREAMING_MODE	False	Enable H.264 streaming mode for pixelflux encoders.
SELKIES_USE_CPU	False	Force CPU-based encoding for pixelflux.
SELKIES_USE_PAINT_OVER_QUALITY	True	Enable high-quality paint-over for static scenes.
SELKIES_PAINT_OVER_JPEG_QUALITY	'1-100'	Allowed JPEG paint-over quality range or a fixed value.
SELKIES_H264_PAINTOVER_CRF	'5-50'	Allowed H.264 paint-over CRF range or a fixed value.
SELKIES_H264_PAINTOVER_BURST_FRAMES	'1-30'	Allowed H.264 paint-over burst frames range or a fixed value.
SELKIES_SECOND_SCREEN	True	Enable support for a second monitor/display.
SELKIES_AUDIO_BITRATE	'320000'	The default audio bitrate.
SELKIES_IS_MANUAL_RESOLUTION_MODE	False	Lock the resolution to the manual width/height values.
SELKIES_MANUAL_WIDTH	0	Lock width to a fixed value. Setting this forces manual resolution mode.
SELKIES_MANUAL_HEIGHT	0	Lock height to a fixed value. Setting this forces manual resolution mode.
SELKIES_SCALING_DPI	'96'	The default DPI for UI scaling.
SELKIES_ENABLE_BINARY_CLIPBOARD	False	Allow binary data on the clipboard.
SELKIES_USE_BROWSER_CURSORS	False	Use browser CSS cursors instead of rendering to canvas.
SELKIES_USE_CSS_SCALING	False	HiDPI when false, if true a lower resolution is sent from the client and the canvas is stretched.
SELKIES_PORT (or CUSTOM_WS_PORT)	8082	Port for the data websocket server.
SELKIES_DRI_NODE (or DRI_NODE)	''	Path to the DRI render node for VA-API.
SELKIES_AUDIO_DEVICE_NAME	'output.monitor'	Audio device name for pcmflux capture.
SELKIES_WATERMARK_PATH (or WATERMARK_PNG)	''	Absolute path to the watermark PNG file.
SELKIES_WATERMARK_LOCATION (or WATERMARK_LOCATION)	-1	Watermark location enum (0-6).
SELKIES_DEBUG	False	Enable debug logging.
SELKIES_ENABLE_SHARING	True	Master toggle for all sharing features.
SELKIES_ENABLE_COLLAB	True	Enable collaborative (read-write) sharing link.
SELKIES_ENABLE_SHARED	True	Enable view-only sharing links.
SELKIES_ENABLE_PLAYER2	True	Enable sharing link for gamepad player 2.
SELKIES_ENABLE_PLAYER3	True	Enable sharing link for gamepad player 3.
SELKIES_ENABLE_PLAYER4	True	Enable sharing link for gamepad player 4.

Language Support - Internationalization

The environment variable LC_ALL can be used to start this image in a different language than English simply pass for example to launch the Desktop session in French LC_ALL=fr_FR.UTF-8.

The web interface has an "IME Input Mode" in Settings which will allow non english characters to be used from a non en_US keyboard on the client. Once enabled it will perform the same as a local Linux installation set to your locale.

Available Distros

All base images are built for x86_64 and aarch64 platforms.

Distro	Current Tag
Alpine	alpine322
Arch	arch
Debian	debianbookworm
Debian	debiantrixie
Enterprise Linux	el9
Fedora	fedora42
Kali	kali
Ubuntu	ubuntunoble

DRI3 GPU Acceleration

For accelerated apps or games, render devices can be mounted into the container and leveraged by applications using:

--device /dev/dri:/dev/dri

This feature only supports Open Source GPU drivers:

Driver	Description
Intel	i965 and i915 drivers for Intel iGPU chipsets
AMD	AMDGPU, Radeon, and ATI drivers for AMD dedicated or APU chipsets
NVIDIA	nouveau2 drivers only, closed source NVIDIA drivers lack DRI3 support

The DRINODE environment variable can be used to point to a specific GPU.

DRI3 will work on aarch64 given the correct drivers are installed inside the container for your chipset.

Nvidia GPU Support

Note: Nvidia support is not available for Alpine-based images.

Nvidia GPU support is available by leveraging Zink for OpenGL. When a compatible Nvidia GPU is passed through, it will also be automatically utilized for hardware-accelerated video stream encoding (using the x264enc full-frame profile), significantly reducing CPU load.

Enable Nvidia support with the following runtime flags:

Flag	Description
--gpus all	Passes all available host GPUs to the container. This can be filtered to specific GPUs.
--runtime nvidia	Specifies the Nvidia runtime, which provides the necessary drivers and tools from the host.

PRoot Apps

All images include proot-apps which allow portable applications to be installed to persistent storage in the user's $HOME directory. These applications and their settings will persist upgrades of the base container and can be mounted into different flavors of Selkies containers. IE if you are running an Alpine based container you will be able to use the same /config directory mounted into a Debian based container and retain the same applications and settings as long as they were installed with proot-apps install.

A list of linuxserver.io supported applications is located HERE.

I like to read documentation

Building images

Application containers

Included in these base images is a simple Openbox DE and the accompanying logic needed to launch a single application. Lets look at the bare minimum needed to create an application container starting with a Dockerfile:

FROM ghcr.io/linuxserver/baseimage-selkies:alpine322
RUN apk add --no-cache firefox
COPY /root /

And we can define the application to start using:

mkdir -p root/defaults
echo "firefox" > root/defaults/autostart

Resulting in a folder that looks like this:

├── Dockerfile
└── root
  └── defaults
    └── autostart

Now build and test:

docker build -t firefox .
docker run --rm -it -p 3001:3001 firefox bash

On https://localhost:3001 you should be presented with a Firefox web browser interface.

This similar setup can be used to embed any Linux Desktop application in a web accesible container.

If building images it is important to note that many application will not work inside of Docker without --security-opt seccomp=unconfined, they may have launch flags to not use syscalls blocked by Docker like with chromium based applications and --no-sandbox. In general do not expect every application will simply work like a native Linux installation without some modifications

In container application launching

Also included in the init logic is the ability to define application launchers. As the user has the ability to close the application or if they want to open multiple instances of it this can be useful. Here is an example of a menu definition file for Firefox:

<?xml version="1.0" encoding="utf-8"?>
<openbox_menu xmlns="http://openbox.org/3.4/menu">
<menu id="root-menu" label="MENU">
<item label="xterm" icon="/usr/share/pixmaps/xterm-color_48x48.xpm"><action name="Execute"><command>/usr/bin/xterm</command></action></item>
<item label="FireFox" icon="/usr/share/icons/hicolor/48x48/apps/firefox.png"><action name="Execute"><command>/usr/bin/firefox</command></action></item>
</menu>
</openbox_menu>

Simply create this file and add it to your defaults folder as menu.xml:

├── Dockerfile
└── root
  └── defaults
    └── autostart
    └── menu.xml

This allows users to right click the desktop background to launch the application.

Full Desktop environments

When building an application container we are leveraging the Openbox DE to handle window management, but it is also possible to completely replace the DE that is launched on container init using the startwm.sh script, located again in defaults:

├── Dockerfile
└── root
  └── defaults
    └── startwm.sh

If included in the build logic it will be launched in place of Openbox. Examples for this kind of configuration can be found in our Webtop repository

Docker in Docker (DinD)

These base images include an installation of Docker that can be used in two ways. The simple method is simply leveraging the Docker/Docker Compose cli bins to manage the host level Docker installation by mounting in -v /var/run/docker.sock:/var/run/docker.sock.

The base images can also run an isolated in container DinD setup simply by passing --privileged to the container when launching. If for any reason the application needs privilege but Docker is not wanted the -e START_DOCKER=false can be set at runtime or in the Dockerfile. In container Docker (DinD) will most likely use the fuse-overlayfs driver for storage which is not as fast as native overlay2. To increase perormance the /var/lib/docker/ directory in the container can be mounted out to a Linux host and will use overlay2. Keep in mind Docker runs as root and the contents of this directory will not respect the PUID/PGID environment variables available on all LinuxServer.io containers.

Nvidia GPU Support

Nvidia is not compatible with Alpine based images

Nvidia support is available by leveraging Zink for OpenGL support. This can be enabled with the following run flags:

Variable	Description
--gpus all	This can be filtered down but for most setups this will pass the one Nvidia GPU on the system
--runtime nvidia	Specify the Nvidia runtime which mounts drivers and tools in from the host

The compose syntax is slightly different for this as you will need to set nvidia as the default runtime:

sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo service docker restart

And to assign the GPU in compose:

services:
  myimage:
    image: myname/myimage:mytag
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [compute,video,graphics,utility]

Development

This container and any downstream images can also be used as a rapid development environment for the Selkies Project. Simply clone the upstream repo and run the container as shown:

git clone https://github.com/selkies-project/selkies.git
cd selkies
docker run --rm -it \
  --shm-size=1gb \
  -e DEV_MODE=selkies-dashboard \
  -e PUID=1000 \
  -e PGID=1000 \
  -v $(pwd):/config/src \
  -p 3001:3001 ghcr.io/linuxserver/webtop bash

The application will be restarted on code changes to the src directory you mounted in and provide feedback for debugging.

The following line is only in this repo for loop testing:

• { date: "01.01.50:", desc: "I am the release message for this internal repo." }