X11ify

Build on top of an existing Docker image to add X11 capabilities.

Build

After cloning or downloading this repository:

cd X11ify
docker build -t <new_image_name>:<new_image_tag> --build-arg IMAGEBASE=<base_image_name>:<base_image_tag> .

In the above command, replace <new_image_name>, <new_image_tag>, <base_image_name>, <base_image_tag> with the desired values.

Run

Unix-like OS often have a program called xhost, which is a server access control program for X. It allows the user to add an delete hostnames which are allowed to make connections to the X server. We will need to ensure that the localhost loopback address (127.0.0.1) is allowed to connect to the X server.

To check the status of the xhost access control and the list of allowed hostnames, simply enter the command xhost. If access control is enabled, you will see the following message:

access control enabled, only authorized clients can connect

If the localhost has been added to the list of authorized hostnames, you will also see:

INET:localhost

If you don't see that message, the localhost must be added to the list of authorized clients by entering the command:

xhost +127.0.0.1

If you are having problems, it's often helpful to reset the list of authorized clients and start again. On some systems that can be accomplished by turning off access control and turning it back on:

xhost + # Turns off access control
xhost - # Turns on access control

On other systems you must manually remove the hosts and add them back again.

Once the system will allow the localhost to connect to X, you can start the docker container by doing:

docker run -it -e DISPLAY=<display_variable> ... <image_name>:<image_tag>

where ... is the rest of your usual docker run command. You must ensure that the DISPLAY variable inside the container is appropriately connected to that of the host. For OSX the display variable is host.docker.internal:0, but the variable may be different on other OS. (Optionally, a command to run inside the container like /bin/bash can be appended to this command.)

Use X11

Once inside the container you should immediately be able to display graphics using X11. You can test this by running xeyes. This should display a window with two eyes whose pupils move as you move the cursor.

Convenience

For your convenience, the script docker_run.sh will take care of checking that you set a DISPLAY environment variable, assuring that the xhost settings are appropriate, and then running the docker image. The script takes three positional parameters:

1. The full list of docker run options you'd like to use (i.e. "-it -e DISPLAY=<display_variable>")
2. The image you'd like to use (i.e. "<image_name>:<image_tag>")
3. (optional) A command to add to the end of the docker run statement (i.e. /bin/bash)

Running this script will look something like:

./docker_run.sh "<options> -e DISPLAY=<display>" "<image_name>:<image_tag>" "<cmd>"

where "<cmd>" is optional.

Security

In order to limit Docker to binding container ports to the localhost, we can set the default IP when binding container ports (default 0.0.0.0). This is a good security practice, which makes sure that the container isn't opening up ports to the outside world. This can be done by directly interacting with the Docker daemon (dockerd), which is the persistent process that manages containers:

dockerd --ip 127.0.0.1

You may need to use sudo to make changes to the daemon. The other option is to edit the daemon.json file at Docker->Preferences->Docker Engine by adding the line:

{
   "ip": "127.0.0.1"
}

Further information about the Docker daemon can be found in the Docker engine reference.

Other options

This repo provides the bare necessities to build and run a Docker image using X11 with some minimal security measures. It does not enable every possible option, nor does it ensure container isolation or seek to avoid all X security leaks. There are many other projects which seek to do this, like x11docker.