linuxserver/docker-webtop

The LinuxServer.io team brings you another container release featuring:

• regular and timely application updates
• easy user mappings (PGID, PUID)
• custom base image with s6 overlay
• weekly base OS updates with common layers across the entire LinuxServer.io ecosystem to minimise space usage, down time and bandwidth
• regular security updates

Find us at:

• Blog - all the things you can do with our containers including How-To guides, opinions and much more!
• Discord - realtime support / chat with the community and the team.
• Discourse - post on our community forum.
• GitHub - view the source for all of our repositories.
• Open Collective - please consider helping us by either donating or contributing to our budget

linuxserver/webtop

Webtop - Alpine, Ubuntu, Fedora, and Arch based containers containing full desktop environments in officially supported flavors accessible via any modern web browser.

Supported Architectures

We utilise the docker manifest for multi-platform awareness. More information is available from docker here and our announcement here.

Simply pulling lscr.io/linuxserver/webtop:latest should retrieve the correct image for your arch, but you can also pull specific arch images via tags.

The architectures supported by this image are:

Version Tags

This image provides various versions that are available via tags. Please read the descriptions carefully and exercise caution when using unstable or development tags.

Application Setup

The application can be accessed at:

• https://yourhost:3001/

Strict reverse proxies

This image uses a self-signed certificate by default. This naturally means the scheme is https. If you are using a reverse proxy which validates certificates, you need to disable this check for the container.

Modern GUI desktop apps may have compatibility issues with the latest Docker syscall restrictions. You can use Docker with the --security-opt seccomp=unconfined setting to allow these syscalls on hosts with older Kernels or libseccomp versions.

Security

[!WARNING] This container provides privileged access to the host system. Do not expose it to the Internet unless you have secured it properly.

HTTPS is required for full functionality. Modern browser features such as WebCodecs, used for video and audio, will not function over an insecure HTTP connection.

By default, this container has no authentication. The optional CUSTOM_USER and PASSWORD environment variables enable basic HTTP auth, which is suitable only for securing the container on a trusted local network. For internet exposure, we strongly recommend placing the container behind a reverse proxy, such as SWAG, with a robust authentication mechanism.

The web interface includes a terminal with passwordless sudo access. Any user with access to the GUI can gain root control within the container, install arbitrary software, and probe your local network.

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.

FullColor 4:4:4 Encoding

If you notice blurry text, particularly light text on a black background, you can send true 8-bit color to the browser by enabling the FullColor 4:4:4 encoding in the sidebar, or by using the jpeg encoding mode.

Note on Hardware Acceleration: Currently, only Nvidia GPUs support encoding this color profile in Zero Copy mode. If FullColor 4:4:4 is enabled on Intel or AMD GPUs, the system will fall back to CPU encoding. This forces the CPU to read the pixels back from the GPU, which will cause a significant decrease in performance.

Hardware Acceleration & Wayland

We have transitioned our desktop containers from X11 to a modern Wayland stack, which is now the default.

Hardware Fallback Note: On x86_64 architecture, the Wayland stack requires a processor with AVX2 support (Intel Haswell generation or newer). If your processor lacks AVX2 (such as older CPUs or certain low-end Celerons), the container will automatically fall back to X11.

Important: GPU acceleration support for X11 is deprecated. Future development for hardware acceleration is focused entirely on the Wayland stack.

If you experience compatibility issues and need to manually disable Wayland (forcing a fallback to X11), you can do so by setting the following environment variable:

• -e PIXELFLUX_WAYLAND=false

Why Wayland?

• 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.
• Modern Stack: Single-application containers utilize Labwc (replacing Openbox) and full desktop containers use KDE Plasma Wayland, providing a more modern, performant, and secure compositing environment while retaining the same user experience.

GPU Configuration

To use hardware acceleration in Wayland mode, we distinguish between the card used for Rendering (3D apps/Desktops) and Encoding (Video Stream).

Configuration Variables:

• DRINODE: The path to the GPU used for Rendering (EGL).
• DRI_NODE: The path to the GPU used for Encoding (VAAPI/NVENC).

If both variables point to the same device, the container will automatically enable Zero Copy encoding, significantly reducing CPU usage and latency. If they are set to different devices one will be used for Rendering and one for Encoding with a cpu readback.

You can also use the environment variable AUTO_GPU=true, with this set the first card detected in the container (IE /dev/dri/renderD128) will be used and configured for Zero Copy.

Intel & AMD (Open Source Drivers)

For Intel and AMD GPUs.

    devices:
      - /dev/dri:/dev/dri
    environment:
      - PIXELFLUX_WAYLAND=true
      # Optional: Specify device if multiple exist (IE: /dev/dri/renderD129)
      - DRINODE=/dev/dri/renderD128
      - DRI_NODE=/dev/dri/renderD128

Nvidia (Proprietary Drivers)

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

Prerequisites:

1. Driver: Proprietary drivers 580 or higher are required. Crucially, you should install the driver using the .run file downloaded directly from the Nvidia website.

   • Unraid: Use the production branch from the Nvidia Driver Plugin.

2. Kernel Parameter: You must set nvidia-drm.modeset=1 nvidia_drm.fbdev=1 in your host bootloader.

   • Standard Linux (GRUB): Edit /etc/default/grub and add the parameter to your existing GRUB_CMDLINE_LINUX_DEFAULT line:

     GRUB_CMDLINE_LINUX_DEFAULT="<other existing options> nvidia-drm.modeset=1 nvidia_drm.fbdev=1"
     

     Then apply the changes by running:

     sudo update-grub
     

   • Unraid (Syslinux): Edit the file /boot/syslinux/syslinux.cfg and add nvidia-drm.modeset=1 nvidia_drm.fbdev=1 to the end of the append line for the Unraid OS boot entry.

3. Hardware Initialization: On headless systems, the Nvidia video card requires a physical dummy plug inserted into the GPU so that DRM initializes properly.

4. Docker Runtime: Configure the host docker daemon to use the Nvidia runtime:

   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker
   

Compose Configuration:

---
services:
  webtop:
    image: lscr.io/linuxserver/webtop:latest
    environment:
      - PIXELFLUX_WAYLAND=true
      # Ensure these point to the rendered node injected by the runtime (usually renderD128)
      - DRINODE=/dev/dri/renderD128
      - DRI_NODE=/dev/dri/renderD128
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [compute,video,graphics,utility]

• Unraid: Ensure you're properly setting the DRINODE/DRI_NODE and adding --gpus all --runtime nvidia to your extra parameters.

SealSkin Compatibility

This container is compatible with SealSkin.

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.

• SealSkin Server: Get it Here
• Browser Extension: Chrome and Firefox.
• Mobile App: iOS and Android

Options in all Selkies-based GUI containers

This container is based on Docker Baseimage Selkies.

-e SELKIES_MANUAL_WIDTH=1920
-e SELKIES_MANUAL_HEIGHT=1080
-e MAX_RES=1920x1080

Language Support - Internationalization

To launch the desktop session in a different language, set the LC_ALL environment variable. For example:

• -e LC_ALL=zh_CN.UTF-8 - Chinese
• -e LC_ALL=ja_JP.UTF-8 - Japanese
• -e LC_ALL=ko_KR.UTF-8 - Korean
• -e LC_ALL=ar_AE.UTF-8 - Arabic
• -e LC_ALL=ru_RU.UTF-8 - Russian
• -e LC_ALL=es_MX.UTF-8 - Spanish (Latin America)
• -e LC_ALL=de_DE.UTF-8 - German
• -e LC_ALL=fr_FR.UTF-8 - French
• -e LC_ALL=nl_NL.UTF-8 - Netherlands
• -e LC_ALL=it_IT.UTF-8 - Italian

Application Management

There are two methods for installing applications inside the container: PRoot Apps (recommended for persistence) and Native Apps.

PRoot Apps (Persistent)

Natively installed packages (e.g., via apt-get install) will not persist if the container is recreated. To retain applications and their settings across container updates, we recommend using proot-apps. These are portable applications installed to the user's persistent $HOME directory.

To install an application, use the command line inside the container:

proot-apps install filezilla

A list of supported applications is available here.

Native Apps (Non-Persistent)

You can install packages from the system's native repository using the universal-package-install mod. This method will increase the container's start time and is not persistent. Add the following to your compose.yaml:

  environment:
    - DOCKER_MODS=linuxserver/mods:universal-package-install
    - INSTALL_PACKAGES=libfuse2|git|gdb

Advanced Configuration

Usage

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

[!NOTE] Unless a parameter is flagged as 'optional', it is mandatory and a value must be provided.

docker-compose (recommended, click here for more info)

---
services:
  webtop:
    image: lscr.io/linuxserver/webtop:latest
    container_name: webtop
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /path/to/data:/config
    ports:
      - 3000:3000
      - 3001:3001
    shm_size: "1gb"
    restart: unless-stopped

docker cli (click here for more info)

docker run -d \
  --name=webtop \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 3000:3000 \
  -p 3001:3001 \
  -v /path/to/data:/config \
  --shm-size="1gb" \
  --restart unless-stopped \
  lscr.io/linuxserver/webtop:latest

Parameters

Containers are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate <external>:<internal> respectively. For example, -p 8080:80 would expose port 80 from inside the container to be accessible from the host's IP on port 8080 outside the container.

Environment variables from files (Docker secrets)

You can set any environment variable from a file by using a special prepend FILE__.

As an example:

-e FILE__MYVAR=/run/secrets/mysecretvariable

Will set the environment variable MYVAR based on the contents of the /run/secrets/mysecretvariable file.

Umask for running applications

For all of our images we provide the ability to override the default umask settings for services started within the containers using the optional -e UMASK=022 setting. Keep in mind umask is not chmod it subtracts from permissions based on it's value it does not add. Please read up here before asking for support.

User / Group Identifiers

When using volumes (-v flags), permissions issues can arise between the host OS and the container, we avoid this issue by allowing you to specify the user PUID and group PGID.

Ensure any volume directories on the host are owned by the same user you specify and any permissions issues will vanish like magic.

In this instance PUID=1000 and PGID=1000, to find yours use id your_user as below:

id your_user

Example output:

uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

Docker Mods

We publish various Docker Mods to enable additional functionality within the containers. The list of Mods available for this image (if any) as well as universal mods that can be applied to any one of our images can be accessed via the dynamic badges above.

Support Info

• Shell access whilst the container is running:

  docker exec -it webtop /bin/bash
  

• To monitor the logs of the container in realtime:

  docker logs -f webtop
  

• Container version number:

  docker inspect -f '{{ index .Config.Labels "build_version" }}' webtop
  

• Image version number:

  docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/webtop:latest
  

Updating Info

Most of our images are static, versioned, and require an image update and container recreation to update the app inside. With some exceptions (noted in the relevant readme.md), we do not recommend or support updating apps inside the container. Please consult the Application Setup section above to see if it is recommended for the image.

Below are the instructions for updating containers:

Via Docker Compose

• Update images:

  • All images:

    docker-compose pull
    

  • Single image:

    docker-compose pull webtop
    

• Update containers:

  • All containers:

    docker-compose up -d
    

  • Single container:

    docker-compose up -d webtop
    

• You can also remove the old dangling images:

  docker image prune
  

Via Docker Run

• Update the image:

  docker pull lscr.io/linuxserver/webtop:latest
  

• Stop the running container:

  docker stop webtop
  

• Delete the container:

  docker rm webtop
  

• Recreate a new container with the same docker run parameters as instructed above (if mapped correctly to a host folder, your /config folder and settings will be preserved)

• You can also remove the old dangling images:

  docker image prune
  

Image Update Notifications - Diun (Docker Image Update Notifier)

[!TIP] We recommend Diun for update notifications. Other tools that automatically update containers unattended are not recommended or supported.

Building locally

If you want to make local modifications to these images for development purposes or just to customize the logic:

git clone https://github.com/linuxserver/docker-webtop.git
cd docker-webtop
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/webtop:latest .

The ARM variants can be built on x86_64 hardware and vice versa using lscr.io/linuxserver/qemu-static

docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset

Once registered you can define the dockerfile to use with -f Dockerfile.aarch64.

Versions

• 10.06.26: - Rebase Alpine images to 3.24.
• 07.05.26: - Deprecate Enterprise Linux tags.
• 07.04.26: - Rebase Ubuntu images to Resolute.
• 26.03.26: - Rebase Fedora images to 44.
• 24.03.26: - Update tags that support Wayland to pass ozone platform for chromium.
• 27.12.25: - Rebase Alpine images to 3.23.
• 17.11.25: - Rebase Fedora images to 43.
• 24.07.25: - Rebase Debian images to Trixie.
• 17.06.25: - Rebase all images to Selkies, drop openbox and icewm, bump Alpine to 3.22, bump Fedora to 42.
• 10.01.25: - Rebase Fedora to 41.
• 06.12.24: - Rebase Alpine to 3.21.
• 26.09.24: - Swap from firefox to chromium on Alpine images.
• 23.05.24: - Rebase Alpine to 3.20, document Nvidia support.
• 22.04.24: - Rebase Ubuntu to Noble.
• 16.04.24: - Add docs on PRoot Apps.
• 14.04.24: - Rebase Fedora to 40.
• 11.02.24: - Add PWA icons and title variants properly.
• 06.02.24: - Update Readme about native language support.
• 29.12.23: - Rebase Alpine to 3.19 and swap back to Firefox.
• 07.11.23: - Rebase Fedora to 39.
• 14.06.23: - Rebase to Debian Bookworm.
• 13.05.23: - Rebase to Alpine 3.18 and Fedora 38.
• 23.03.23: - Rebase all Webtops to KasmVNC base image.
• 21.10.22: - Rebase xfce to Alpine 3.16, migrate to s6v3.
• 12.03.22: - Add documentation for mounting in a GPU.
• 05.02.22: - Rebase KDE Ubuntu to Jammy, add new documentation for updated gclient, stop recommending priv mode.
• 21.09.21: - Add Fedora and Arch images, show seccomp settings in readme.
• 26.09.21: - Rebase to Alpine versions to 3.14.
• 20.04.21: - Initial release.