tldr Running a GUI program in Docker takes a little work. So does running a GUI program using SSH X11 forwarding. Putting the two together is the most fun of all. /tldr
Docker is an interesting technology to work with, because sometimes it feels like just regular coding, and sometimes it feels like typing with oven mitts on. Today was an oven mitt day.
The goal was to get a GUI program to run, in Docker, with the X server on the other side of an SSH tunnel. First step, to remove as many variables as possible, was to make a Docker container with a basic X11 client application for testing. I did a little searching on Docker Hub, but didn’t immediately find what I wanted. But it’s more fun to make one anyway.
This Dockerfile will do the trick:
FROM centos RUN yum install -y xeyes CMD ["/usr/bin/xeyes"]
We can then run
docker build -t xeyes . from the directory with the
Dockerfile and have an image we can run with
docker run xeyes. Of
course, it isn’t quite that simple, because
xeyes inside the container
won’t be able to see our X server. For starters, we need to pass our
DISPLAY environment variable through to the container:
docker run --env="DISPLAY" xeyes. However, this still won’t work
xeyes won’t be able to connect to the X server.
Normally, to allow the client to connect to the X server
would mean mapping the local UNIX domain socket into the
Docker container using the
--volume argument. However, in this case the X
server was on the other side of an SSH tunnel from the machine running the
Docker container. With SSH X11 forwarding, instead of a UNIX domain socket,
clients communicate with a TCP/IP socket on port
Usually the ports start at 6010, which corresponds with a
The port is opened on the remote machine by the SSH daemon on behalf of the SSH client. All traffic is forwarded through the SSH connection, where the SSH client sends it on to whatever X server is configured.
So we need our Docker container to connect to port 6010 on the host. Usually
processes in a Docker container “just work” as a network client; for example,
yum in a CentOS container, like we did in the
works just fine. This works because Docker creates a “bridge” interface and
handles routing all outgoing traffic to the right address.
However, in this case, the SSH daemon only binds its port to the
on the host. In bridge mode, the
lo interface inside the container is different
lo interface on the host. So the bound port isn’t visible from inside
Fortunately, Docker has a “host” network mode, where it allows the container to see the same network stack that the host uses. As long as network isolation isn’t a necessity, this works quite well. Our Docker run command is now:
docker run --net=host --env="DISPLAY" --rm xeyes
Here I got a little stuck. The error message was still
Error: Can't open display,
just as when I was using bridge mode. Time to create an interactive session so we
can do a little debug:
docker run -it --net=host --env="DISPLAY" --rm xeyes /bin/bash
ss -an inside the container we can see that something is listening on
port 6010. (This is CentOS 7, so the old standby
netstat is no longer there by
default.) So why can’t it open the display? I next installed
nc inside the
container, and used that great little program to confirm that I could connect to
localhost:6010. Out of an excess of paranoia, I ran
sudo tcpdump -nS -i lo port 6010
on the host, and sure enough I could see X11 traffic briefly over that port when
xeyes inside the interactive container.
That was when I realized that the issue must be X11 authentication. I had discounted this possibility out of a misguided belief that X11 authentication issues led to different error messages.
There are a few ways to pass X11 authentication through to the container; my belief
is that the easiest is to give the container access to the
.Xauthority file. The
file needs to wind up in
/root since that is the default user running processes
inside the container. So one more change to the run script:
docker run --net=host --env="DISPLAY" --volume="$HOME/.Xauthority:/root/.Xauthority:rw" xeyes
And it finally worked. Of course I was a little irritated that the issue ended up being an “Introduction to Remote X11” issue. But along the way, I picked up a few tools to help debug these kinds of issues, so it wasn’t a complete waste of time.