x11docker: Run GUI applications in Docker or podman containers.

Avoid X security leaks and enhance container security

Latest release is v7.8.0

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 and podman allow to run applications in an isolated container environment. Containers need much less resources than virtual machines for similar tasks.
• Docker and podman 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. x11docker supports Wayland as well.
• 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 support of this VM based version is experimental only and some features won't work; however, basic functionality is given. Instead, rather use x11docker with the native and more performant "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 less 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 or podman. 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 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, --wayland and --xw. Most lightweight are nxagent and Xephyr.

• Overview of all possible X server and Wayland options.
  • Hints to use option --xorg within X.
• Indicate a desktop environment with