Supported tags and respective
latest-jessie(Dockerfile-jessie): Xpra version 2.0-r15315M-1 based on Debian Jessie
latest-xenial(Dockerfile-xenial): Xpra version 2.0-r15319-1 based on Ubuntu Xenial (16.04)
A Got-a-feeling Example
Type the following command:
> docker run --rm --env XPRA_OPTIONS="--exit-with-children --bind-tcp=0.0.0.0:14500 --html=on" --publish 14500:14500 mgtsai/dockerui.base-xpra:latest-jessie sh -c "xclock & xterm"
and then browse http://yourhost:14500/. Oh yeah! An
xclock and an
xterm are shown on the web browser.
Running X applications in a Docker container
Users can use
docker create or
docker run to execute the specified X application in the created container, similar to other typical non-GUI commands running in containers. The X application communicates to the Xpra server with the environment variable
DISPLAY=:0, by the UNIX domain socket
/tmp/.X11-unix/X0, which means only local X applications are allowed to connect to the Xpra server, but remote applications are prohibited.
In the provided images, only few simple X applications are pre-installed, such as
xterm, ... etc. Typically one user builds his/her own
Dockerfile by inheriting one of the provided images of this project, and install the wished GUI program specified in the
Dockerfile. The following
Dockerfile example provides the execution of X file manager
FROM mgtsai/dockerui.base-xpra:latest-jessie RUN apt-get update && apt-get install -q -y xfe ENV XPRA_OPTIONS="--exit-with-children --bind-tcp=0.0.0.0:14500" EXPOSE 14500 CMD xfe
Xpra startup options
By default, the Xpra server only provides UNIX domain sockets for Xpra client connections. To enable remote client connection via network, the Docker environment variable
XPRA_OPTIONS is applied when creating containers, incorporated in the following Xpra startup command:
xpra start $DISPLAY --no-daemon $XPRA_OPTIONS --start-child="$CMD"
For example, applying
XPRA_OPTIONS="--bind-tcp=0.0.0.0:14500" means Xpra clients can connect to the server via the insecure TCP port 14500.
Otherwise, users can specify the Xpra option
XPRA_OPTIONS to enable automatically terminating while the X application terminates.
For detailed usage of Xpra options, you may reference http://xpra.org/manual.html.
Specifying effective UID and GID of the Xpra server and X appications
In some scenarios, we would like to specify the application's effective UID/GID, especially when working with Docker volumes. For example, an IDE program works with user's development project sources, and the whole bunch of source files may be preferred to be located on the host file system, by binding host directories with container volumes. Since the files on the host file system have their own UID/GID which should not be altered inside the container, we need to specify the effective UID/GID of the running X application (a.k.a. IDE programs) to assign the right permission to access the cooperative files.
We let the determination of the effective UID/GID of an X application being lately bound on the Docker container creating phase (not on the image building phase) to provide more flexibility for users. While creating a Docker container, applying environment variables
GUEST_GID for specifying user/group names and effective UID/GID of the Xpra server and X applications.
When starting a container, it also creates the corresponding home directory of
GUEST_USER. The home directory is specified by the environment variable
GUEST_HOME, with default value
"/home/$GUEST_USER". Thus, the X application knows the information of which user runs it and its home directory, similar to ones run on a normal physical/virtual machine.
Container startup execution sequence
Despite of regular Docker command running as specified
GUEST_GID, sometimes we wish to do extra operations with root permission. When building user's own
Dokerfile, the script
/docker/preexecAsRoot is used for this purpose. Before starting the Xpra server,
/docker/preexecAsRoot is executed with root permission for initializing necessarities, such as other cooperative daemons.
Briefly, when a container start, the following sequence would be executed:
/docker/preexecAsRootwith effective UID/GID as 0/0
- Starts the Xpra server with
- Runs the specified X application with
Default values of environment variables
|Environment variable||Default value|
xlockas well as the Xpra server by providing TCP port 14500 (INSECURE)
> docker run --rm --env XPRA_OPTIONS="--exit-with-children --bind-tcp=0.0.0.0:14500" mgtsai/dockerui.base-xpra:latest-jessie xclock
xeyesas well as the Xpra server with UID 2001 and GID 2001 by providing TCP port 14500 (INSECURE)
> docker run --rm --env XPRA_OPTIONS="--exit-with-children --bind-tcp=0.0.0.0:14500" --env GUEST_UID=2001 --env GUEST_GID=2001 mgtsai/dockerui.base-xpra:latest-jessie xeyes
xcalcas well as the Xpra server by providing TCP port 14500 and HTTP server with URL http://container:14500/index.html (INSECURE) for showing
> docker run --rm --env XPRA_OPTIONS="--exit-with-children --bind-tcp=0.0.0.0:14500 --html=on" mgtsai/dockerui.base-xpra:latest-jessie xcalc
xeditas well as the Xpra server by providing TCP port 14500 with password authentication (INSECURE)
> docker run --rm --env XPRA_OPTIONS="--exit-with-children --bind-tcp=0.0.0.0:14500 --auth=password:value=yourpass" mgtsai/dockerui.base-xpra:latest-jessie xedit
xtermas well as the Xpra server by providing TCP port 14500 with SSL and password authentication, using
./demofiles/cert/demo.pemon host as SSL certification
> docker run --rm --env XPRA_OPTIONS="--exit-with-children --bind-ssl=0.0.0.0:14500 --ssl-cert=/home/user/demofiles/cert/demo.pem --auth=password:value=yourpass" --volume `pwd`/demofiles:/home/user/demofiles mgtsai/dockerui.base-xpra:latest-jessie xterm
Dockerfileexamples are provided in the directory