Running X11 applications like xeyes in Docker

Running xeyes is a useful proof of concept useful for containerizing applications which need UIs.

Christian Hujer, Software Crafter and CEO / CTO of Nelkinda Software Craft Private Limited
First Published:
by NNelkinda Software Craft Private Limited
Last Modified:
by Christian Hujer
Approximate reading time:
Figure -1: xeyes in Docker

Running xeyes in Docker seems a bit like an unnecessary stunt. True, running xeyes in Docker has no practical purpose in itself. But the whole point is actually not about xeyes. It is about how to get an X11 application running in Docker in general.

1 Purpose

I came across this problem when I actually wanted to do something else. For a client project, I need to setup a IBM Lotus Domino server and fill it with sample data. It seems that without a GUI, performing this setup ranges from hassle to impossible. Whether something is good server software if it can't be configured from a terminal window is a different story. Hello, IBM, are you listening? I already messed up my system once when trying to get IBM Lotus Notes installed to administer IBM Lotus Domino. I didn't want this to happen again. So I thought of containerizing the two IBM Lotus applications. But when doing so, there is a challenge: How do I get the UI of the IBM Lotus applications from within Docker display on my Docker host? I could've used VNC. But mind you, I'm running Linux inside Linux, so why not use X11 directly?

So, the purpose of running xeyes in Docker is a proof of concept. There are many things why running applications inside Docker could go wrong. X11 is one of the things that can go wrong. With running xeyes in Docker, there is a proof of concept that running X11 applications inside docker works. It helps isolating and fixing one problem at a time.

2 Ingredients

The ingredients are:

2.1 X11 Considerations

You should only run applications this way which you trust. The applications in the container will be able to use X11 to intercept mouse and keyboard. For example, they could perform key-logging. So, only do this with trust-worthy applications.

Security Alert! Only run trustworthy applications this way!

If your reason for containerization is not security, it's just fine. But if the reason for containerization was security, you should probably prefer VNC over X11.

3 The Dockerfile

The Dockerfile has to do the following things:

FROM debian:latest

RUN apt-get update && apt-get install -y x11-apps
RUN rm -rf /tmp/* /usr/share/doc/* /usr/share/info/* /var/tmp/*
RUN useradd -ms /bin/bash user

USER user
ENTRYPOINT ["/bin/sh", "-c", "$0 \"$@\"", "xeyes"]
Listing 3-1: Dockerfile to run xeyes

3.1 Explanation

For more information what these Dockerfile commands mean and how they work, refer to [Dockerfile].

You can build the container with docker build -t my-xeyes

4 Running it

The first attempt to run the image would look like this:

$ docker run -it --rm --name xeyes my-xeyes
No protocol specified
Error: Can't open display: :0
$ echo $?

The error message means that xeyes in the container was unable to connect to the X11 server. There are two to three reasons for this.

We need to share the current user's .Xauthority with the xeyes docker container. For that, we can simply mount the .Xauthority file as volume. But there's a caveat: The user user inside the container has id 1000. The id of the current user might be different. So we need to grant access to the user user by granting access to 1000.

To grant access, run setfacl -m user:1000:r ${HOME}/.Xauthority. The volume is configured by adding -v ${HOME}/.Xauthority:/home/user/.Xauthority to docker run.

Note what this means. Such volumes are file system sharing between the host and the container. For such shared file systems, the user ids between the container and the host need to match.

These steps alone will not yet work. The .Xauthority file is shared successfully, but X11 will still deny access. The reason is that the docker container thinks it's a different machine than what was configured automatically in the .Xauthority during login. You can change what the docker container thinks of networks. Add the option --net=host to the docker run command.

To see the full command sequence, look at the next chapter, which shows a shell script for convenience.

5 Shell Script for Convenience

The following shell script contains all the commands to run xeyes in docker.

setfacl -m user:1000:r ${HOME}/.Xauthority
docker build -t my-xeyes .
exec docker run \
    -it \
    --rm \
    --name xeyes \
    --net=host \
    -e DISPLAY \
    -v ${HOME}/.Xauthority:/home/user/.Xauthority \
    my-xeyes \
Listing 5-1:, a shell script to run xeyes in Docker

5.1 Explanation of the Shell Script

5.2 Examples

6 Limitations and Alternatives

As already mentioned, there is a security consideration around X11 applications. Besides, this solution only works in situations where the host runs X11 directly. This means success is almost guaranteed if the host that runs docker runs X11 itself. That is the case on Linux and FreeBSD. On other operating systems, such as Mac OS X and Windows, further steps would be required.

There are at least two options in that case.