x11docker: Run GUI applications in Docker or podman containers.

Avoid X security leaks and enhance container security

Table of contents

• Introduction
  • Docker Desktop or Docker Engine
  • TL;DR
  • Features
  • Supported systems
• Terminal syntax
• Options
  • Choice of X servers and Wayland compositors
  • Desktop or seamless mode
  • Internet access
  • Shared folders and HOME in container
  • GPU hardware acceleration
  • Clipboard
  • Sound
  • Webcam
  • Printer
  • Language locales
  • Wayland
  • Init system
  • DBus
  • Container runtime
  • Backends other than docker
  • Preconfiguration with --preset
    • Default preset for all x11docker sessions
• Security
  • Security weaknesses
  • Options degrading container isolation
  • Sandbox
  • Security and feature check
• Installation
  • Installation from distribution repositories
  • Manual installation
    • Installation options
    • Installed files
    • Shortest way for first installation
    • Minimal installation
    • Installation on MS Windows
    • Deinstallation
• Dependencies
• Troubleshooting
  • Core checks
  • Privilege checks
  • Other checks
• Contact
  • Issues
  • Contributing
  • Support
• Donation
• Examples
  • Single applications
  • Desktop environments
  • Adjust images for your needs
  • Screenshots

Introduction

x11docker allows to run graphical desktop applications (and entire desktops) in Linux containers.

• Container tools like Docker, podman and nerdctl allow to run applications in an isolated container environment. Containers need much less resources than virtual machines for similar tasks.
• Docker, podman and nerdctl do not provide a display server that would allow to run applications with a graphical user interface.
• x11docker fills the gap. It runs an X display server and provides it to containers. X servers can run from host or in a container of image x11docker/xserver.
• Additionally x11docker does some security setup to enhance container isolation and to avoid X security leaks. This allows a sandbox environment that fairly well protects the host system from possibly malicious or buggy software.

Software can be installed in a deployable image with a rudimentary Linux system inside. This can help to run or deploy software that is difficult to install on several systems due to dependency issues. It is possible to run outdated versions or latest development versions side by side. Files to work on can be shared between host and container.

x11docker wiki provides some how-to's for basic setups without x11docker.

Docker Desktop or Docker Engine

Since a while Docker distributes a version called "Docker Desktop" that runs Docker in a QEMU VM. x11docker is not designed to support this VM based version. Instead, use x11docker with the native "Docker Engine Server version" that uses your host kernel to run containers.

• If you install Docker from your distribution's repository, you'll likely get this native version.
• The supported native Docker Engine package name is mostly docker.io or docker-ce, in opposite to the non-supported VM based docker-desktop package.
• If you prefer podman over Docker, you don't need to care about this difference.

TL;DR

For a quick start:

• Install x11docker with:

  curl -fsSL https://raw.githubusercontent.com/mviereck/x11docker/master/x11docker | sudo bash -s -- --update
  

• Install dependencies:
  • Either pull image x11docker/xserver or install at least nxagent or xpra and xephyr.
• Run a GUI in container with:

  x11docker IMAGENAME [COMMAND]
  

• Add options:
  • --desktop for a desktop environment in image.
  • --gpu for hardware acceleration.
• Examples:

  x11docker x11docker/xfce thunar
  x11docker --desktop x11docker/xfce
  x11docker --gpu x11docker/xfce glxgears
  

Features

• Focus on security:
  • Avoids X security leaks by running additional X servers.
  • Restricts container capabilities to bare minimum.
  • Container user is same as host user to avoid root in container.
• Low dependencies:
  • No obliging dependencies on host beside X and one of docker, podman or nerdctl. Recommended: nxagent and Xephyr, alternatively image x11docker/xserver.
  • No dependencies inside of images except for some optional features.
• Several optional features like GPU, sound, webcam and printer support.
• Remote access with SSH, VNC or HTML5 possible.
• Easy to use. Examples:
  • x11docker x11docker/fvwm xterm
  • x11docker --desktop --size 320x240 x11docker/lxde (needs nested X server Xephyr)

Supported systems

x11docker runs on Linux and (with some setup and limitations) on MS Windows. x11docker does not run on macOS except in a Linux VM.

Terminal syntax

Just type x11docker IMAGENAME [COMMAND].

• Get an overview of options with x11docker --help.
  • For desktop environments in image add option -d, --desktop.
  • For internet access use option -I, --network.
  • To run without X at all use option -t, --tty.
  • Get an interactive TTY with option -i, --interactive.
  • See generated container backend command (and further infos) with option --debug.
• If startup fails, look at chapter Troubleshooting.

General syntax:

Usage:
To run a container on a new X server:
  x11docker IMAGE
  x11docker [OPTIONS] IMAGE [COMMAND]
  x11docker [OPTIONS] -- IMAGE [COMMAND [ARG1 ARG2 ...]]
  x11docker [OPTIONS] -- CUSTOM_RUN_OPTIONS -- IMAGE [COMMAND [ARG1 ARG2 ...]]
To run a host application on a new X server:
  x11docker [OPTIONS] --backend=host COMMAND
  x11docker [OPTIONS] --backend=host -- COMMAND [ARG1 ARG2 ...]
  x11docker [OPTIONS] --backend=host -- -- COMMAND [ARG1 ARG2 ...] -- [ARG3]
To run only an empty new X server:
  x11docker [OPTIONS] --xonly

CUSTOM_RUN_OPTIONS are just added to the docker|podman|nerdctl run command without a serious check by x11docker.

Options

Description of some commonly used feature options.

• Some of these options have dependencies on host and/or in image. Compare wiki: feature dependencies.
• For often used option combinations you can make shortcuts with option --preset.

Choice of X servers and Wayland compositors

If no X server option is specified, x11docker automatically chooses one depending on installed dependencies and on given or missing options --desktop, --gpu and --wayland. Most recommended are nxagent and Xephyr.

• Overview of all possible X server and Wayland options.
  • Hints to use option --xorg within X.
  • Use option -t, --tty to run without X at all.

Desktop or seamless mode

x11docker assumes that you want to run a single application in seamless mode, i.e. a single window on your regular desktop. If you want to run a desktop environment in image, add option --desktop.

• Seamless mode is supported with options --nxagent and --xpra. As a fallback insecure option --hostdisplay is possible.
• Desktop mode with --desktop is supported with all X server options except --hostdisplay. If available, x11docker prefers --xephyr and --nxagent.
• Special case: Single applications with a window manager (option --wm).
  • If neither nxagent nor xpra are installed, but x11docker finds a desktop capable X server like Xephyr, it avoids insecure option --hostdisplay and runs Xephyr with a window manager.

Internet access

By default x11docker disables Network access for containers with --network=none because it targets best possible container isolation. To allow internet access set option -I or --network.

Shared folders, volumes and HOME in container

Changes in a running container system will be lost, the created container will be discarded. For persistent data storage you can share host directories or volumes:

• Option -m, --home creates a host directory in ~/.local/share/x11docker/IMAGENAME that is shared with the container and mounted as its HOME directory. Files in container home and user configuration changes will persist. x11docker creates a softlink from ~/.local/share/x11docker to ~/x11docker.
  • You can specify another host directory for container HOME with --home=DIR.
  • You can specify a volume for container HOME with --home=VOLUME.
• Option --share PATH mounts a host file or folder at the same location in container.
  • You can also specify a volume with --share VOLUME.
  • --share PATH:ro restricts to read-only access.
  • Device files in /dev are supported, too.
• Special cases for $HOME:
  • --home=$HOME will use your host home as container home. Discouraged, use with care.
  • --share $HOME will symlink your host home as a subfolder of container home.

Note that x11docker copies files from /etc/skel in container to HOME if HOME is empty. That allows to provide predefined user configurations in the image.

GPU hardware acceleration

Hardware acceleration for OpenGL is possible with option -g, --gpu.

• This will work out of the box in most cases with open source drivers on host. Otherwise have a look at wiki: feature dependencies.
• Closed source NVIDIA drivers need some setup and support less x11docker X server options for driver version < v470.x and Xwayland < v22.1.2.

Clipboard

Clipboard sharing is possible with option -c, --clipboard [=ARG].

• Optional arguments superv and altv only provide host clipboard content to container if keys [SUPER][v] or [ALT][v] are pressed.
• Optional argument oneway only transfers clipboard content from container to host.

Sound

Sound is possible with options -p, --pulseaudio and --alsa.

• For pulseaudio sound with --pulseaudio you need pulseaudio on host and pulseaudio (at least the pulseaudio client libraries) in image. Compare wiki: feature dependencies.
• For ALSA sound with --alsa you might need to specify a sound card with e.g. --alsa=Generic. Get a list of available sound cards with aplay -l.

Webcam

Webcams on host can be shared with option --webcam.

• If webcam application in image fails, install --gpu dependencies in image. Compare wiki: feature dependencies.
• guvcview needs --pulseaudio or --alsa.
• cheese and gnome-ring need --init=systemd.

Printer

Printers on host can be provided to container with option --printer.

• It needs cups on host, the default printer server for most linux distributions.
• The container needs cups client libraries in image. Compare wiki: feature dependencies.

Language locales

x11docker provides option --lang for flexible language locale settings.

• --lang without an argument sets LANG in container to same as on host. Same as --lang=$LANG
• x11docker will check on container startup if the desired locale is already present in image and enable it.
• If x11docker does not find the locale, it creates it on container startup. This needs some locale packages in image. Compare wiki: feature dependencies.
• Examples: --lang=de for German, --lang=zh_CN for Chinese, --lang=ru for Russian, --lang=$LANG for your host locale.
• For support of chinese, japanese and korean characters install a font like fonts-arphic-uming in image.
• Keyboard input methods like fcitx-pinyin are possible with some container setup. Compare ticket #269.

Wayland

To run Wayland instead of an X server x11docker provides options --wayland, --weston, --kwin and --hostwayland. For further description loot at wiki: Description of Wayland options.

• Option --wayland automatically sets up a Wayland environment. It regards option --desktop.
• Options --weston and --kwin run Wayland compositors weston or kwin_wayland.
• Option --hostwayland can run