x11docker

To quickly set up and run a GUI application in a container, follow these steps:

1. Install x11docker using the official installation script:

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

2. Install dependencies: You must either pull the x11docker/xserver image or install host-side tools like nxagent, xpra, or xephyr.
3. Run a GUI application: Use the syntax x11docker IMAGENAME [COMMAND].

Common Examples:

• Run a specific application: x11docker x11docker/xfce thunar
• Run a full desktop environment: x11docker --desktop x11docker/xfce
• Run with GPU hardware acceleration: x11docker --gpu x11docker/xfce glxgears

x11docker requires an X server. You have two main approaches:

1. Use the automatic x11docker/xserver image

This is the easiest method as it provides most optional dependencies and several X servers/Wayland compositors without requiring host installation.

2. Install dependencies on the host

If you prefer to use host-side X servers, the recommended base commands to install are: nxagent, Xephyr, weston, Xwayland, xdotool, xauth, xinit, xclip, xhost, xrandr, and xdpyinfo.

x11docker automatically selects an X server based on installed dependencies and options like --desktop, --gpu, --wayland, and --xw.

• Seamless mode (single window on host desktop): Supported via --nxagent or --xpra. Use --hostdisplay as an insecure fallback.
• Desktop mode (full desktop environment): Use --desktop. x11docker prefers --xephyr or --nxagent.
• Wayland mode: Use --wayland for a Wayland environment, --weston to run the weston compositor, or --hostwayland for seamless integration with host Wayland desktops (Gnome 3, KDE 5, Sway).
• Side-by-side X and Wayland: Use --weston-xwayland --wayland or, if on a host Wayland desktop, --hostdisplay --hostwayland.
• No GUI: Use -t, --tty to run without X or Wayland.

x11docker --wayland x11docker/xfce xfce4-terminal

x11docker requires bash and either docker or podman to run. To ensure you have the latest version, use the built-in update commands.

• To update to the latest stable release: x11docker --update
• To update to the latest beta: x11docker --update-master

Because Docker Hub images may become outdated, it is recommended to build images locally using the --build option. You can use existing Dockerfiles from the mviereck GitHub repositories (specifically those starting with dockerfile-x11docker) to build your own images.

To build a specific image locally, use:

x11docker --build x11docker/fvwm

x11docker is a bash script. You can install it via distribution repositories or manually.

Manual Installation via Script

To install or update the latest release from GitHub, use the following commands:

Using sudo (recommended for system-wide installation):

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

As root:

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

Minimal Installation

You can run x11docker without a full installation by executing the script directly: bash x11docker or ./x11docker. For a manual system-wide setup, make the script executable (chmod +x x11docker) and move it to a directory in your PATH, such as /usr/local/bin.

Create shortcuts for complex option combinations using --preset FILENAME. Presets are stored in ~/.config/x11docker/preset/ or /etc/x11docker/preset/.

Example Multimedia Preset: Create a file ~/.config/x11docker/preset/multimedia with:

--gpu
--webcam
--printer
--pipewire
--clipboard
--share ~/Videos
--share ~/Music

Run it with: x11docker --preset=multimedia jess/vlc

Default Preset: A file named default in the preset directories acts as a global configuration file for all x11docker sessions (e.g., to always use --backend=podman).

To add custom applications or make persistent changes to an x11docker image, create a new Dockerfile using an existing x11docker image as the base (FROM).

Example Dockerfile to add VLC to an Xfce desktop:

# xfce desktop with VLC media player
FROM x11docker/xfce
RUN apt-get update && apt-get install -y vlc

For optimal performance and feature support, use the native Docker Engine Server version (typically provided by packages like docker.io or docker-ce) rather than Docker Desktop.

Docker Desktop runs Docker inside a QEMU VM, and while x11docker provides experimental support for it, some features may not work. If you use Podman, you do not need to worry about this distinction.

By default, x11docker uses an unprivileged user similar to your host user. If the application requires a different user:

1. Check image's predefined user: docker inspect --format '{{.Config.User}}' IMAGENAME
2. Use the image's user: Use --user=RETAIN to enable the user specified in the image.
3. Use root: Use --user=root (may require --cap-default).

Certain applications require system daemons:

• DBus: Install dbus in the image and use the --dbus option.
• Systemd: Install systemd in the image and use the --init=systemd option.