Containers are not usually associated with GUI applications, but there may be times when one might still want to run such a program inside a container, for example to isolate the application’s dependencies. Installing a GUI application in a container means that not only the application, but also all its specific dependencies are encapsulated inside the container (respectively, the container image), and can therefore reliably be removed from the system in a single step.
In this example, I will use the pinta paint program, which requires the Mono runtime. I do not use any other programs that depend on Mono, and as I like to keep my system installation relatively clean, I would like to isolate the application and its libraries as much as possible.
Getting a GUI application to run in a container requires several distinct steps:
- Installing the application and its dependencies in a container.
- Letting the application and the host’s window system talk to each other.
- Creating an image of the installed application for later use.
- (Optional:) Letting the application and the host share files.
This assumes that Docker (or an equivalent container management system) is already installed and running on the host, and that the user has the necessary permissions to use it.
To distinguish which commands are issued on the host, and which are issued in an interactive container session, the respective prompts are shown in the examples below!
Also, this example assumes a Linux environment throughout.
Installing the Application
The first step is to obtain a suitable base image. Here, we will use Ubuntu:
host> docker image pull ubuntu:jammy
Next, we log into the container and install the desired application.
We could simply run the container using
docker container run --rm -it ubuntu
-it means to run an interactive session and to attach a terminal,
--rm will shut down and remove the container once the interactive
session ends), but instead we will use the following command, so that
the container can access the graphical display later. (This will be
explained in the next section.)
host> docker container run --rm --net host -v /tmp/.X11-unix:/tmp/.X11-unix -it ubuntu
Now we can install the desired application:
container# apt update container# apt install -y pinta
The installation process will ask for the current timezone; enter the appropriate information.
Sharing the Screen
Attempting to run pinta from within the container at this point will most likely fail. For an application to launch a window requires three things:
- The application (the “client”) must know how to talk to the windowing system (the “server” or “display server”).
- The application must have appropriate permission to access the server.
- The application must tell the server where the window should appear.
On Unix, running X11, local client applications usually communicate with
the display system via a Unix domain socket. A domain socket is visible
in the fileystem; and the one used for X11 communication is found
in the directory
-v option provided when starting the container created a “bind mount”:
a directory on the host system has been mapped to a directory of the
filesystem inside the container. (The path before the colon refers
to the host filesystem; the path after the colon refers to the
container filesystem. Here the respective paths are equal, later
we will see an example where this is not the case.) For the client
inside the container to be able to communicate with the display server
on the host also requires to use the “host” networking mode, as specified
An application not only needs to be able to communicate with the display server, it also needs to authenticate itself. There are several different ways for X11 applications to authenticate themselves to the server; for now, we will use one of the simplest. On the host, issue the command:
host> xhost +local:
This allows any local application to access the display server. (If
you are paranoid, you may want to switch this behavior off by issuing
xhost -local: when you have shut the GUI application and
Finally, we need to tell the application which display to use. This is
done via the
DISPLAY environment variable inside the container:
container# export DISPLAY=:0
Now, you should be able to execute the command:
and have the window appear on your screen.
Creating an Image
We can create and save an image of the currently running container. This way, we will be able to run the application without having to to go through the entire installation process again in the future.
On the host, run
docker container ls to find the ID of the running
container, and then (still on the host), create an image of the container
by feeding its ID to docker’s
commit command (substitute the real ID,
host> docker commit <ID> pinta:pinta
This will create a new image, named
pinta:pinta, as you can verify
docker image ls (on the host). It is not necessary to
stop the container before creating an image!
It is now safe to shut down the application and exit the container.
Because the container was started with the
--rm option, it will
be removed once the interactive session ends. You may also want to
turn off access to the display server by issuing
xhost -local: on
the host at this point.
Sharing a Directory
We may generally want to share files between the host system and the containerized application. Using pinta, as an example, we may want to read a graphics file from the user’s (host) home directory, modify it, and write it back.
Docker’s bind mounts provide a convenient method to accomplish this. In a bind mount, a directory (or even a single file) in the host’s filesystem is mapped to an entity in the container’s filesystem. In contrast with docker volumes, bind mounts are not managed by Docker, and their backing store exists solely in the host’s filesystem.
In the following, let’s assume that there is a directory called
in the user’s home directory on the host. Then we can run a containerized
version of pinta using the following command line, using the new image
that was created in the previous step (remember to run
host> docker container run --rm \ --net host \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v /home/janert/pinta:/pinta \ -e DISPLAY \ pinta:pinta pinta
Compared to the previous
run command, this one includes two bind
mounts: one is for the Unix domain socket required by X11. The other
one maps the directory
/home/janert/pinta on the host system to the
/pinta in the container. Any file placed into the directory
on the host will be visible to the pinta process inside the container,
and pinta can write its results back to that location as well.
Also new is the
-e option that sets the
DISPLAY environment variable
inside the container to the value it has outside the container. (You can
also supply a value explicitly:
The command runs the newly created image
pinta:pinta, and runs the
pinta command inside of the container once the container starts. No
interactive session will be started. When pinta is ended, the container
will be removed.
I have greatly benefited from the James Walker' article How to Run GUI Applications in a Docker Container, in particular in regards to the explanation of the X11 domain socket. I also highly recommend his comprehensive selection of excellent articles on Docker at How-To Geek.