Using a docker container with a GUI

Last modified

November 27, 2024

Docker is an open platform for developing, shipping, and running applications. Docker provides the ability to package and run an application in a loosely isolated environment called a container. Containers are lightweight and contain everything needed to run the application, so you do not need to rely on what is currently installed on the host system. You can easily share containers while you work, and be sure that everyone you share with gets the same container that works in the same way.

Dockerfile – is a text document that contains all the commands you would normally execute manually in order to build a Docker image. The instructions include a choice of operating system and all the libraries we need to install into it. Docker can build images automatically by reading the instructions from a Dockerfile.
Docker Images – are the basis of containers. A Docker image is an immutable (unchangeable) file that contains the source code, libraries, dependencies, tools, and other files needed for an application to run.
Docker Container – A container is, ultimately, just a running image.

Docker installation

Docker can be installed on Windows, macOS, and Linux. Please visit the Docker website for downloading and installation instructions. Note, you will need admin access to your system.

Please check the Issues/troubleshooting session at the end of this page if you encounter some problems during installation. If your problem is not listed you can add it as an issue in the main repository.

Verify Docker installation

Run the following commands in the terminal (see below) to verify your installation:

  • docker --version
    Will output the version number
  • docker run hello-world
    Will output a welcome message. If you haven’t run this command before, you will receive the message Unable to find image: ‘hello-world:latest’ locally. Docker will then proceed by downloading and running the latest version from DockerHub.

Terminal access

Linux
The default Unix Shell for Linux operating systems is usually Bash. On most versions of Linux, it is accessible by running the (Gnome) Terminal or (KDE) Konsole or xterm, which can be found via the applications menu or the search bar. If your machine is set up to use something other than bash, you can run it by opening a terminal and typing bash.

macOS
For a Mac computer, the default Unix Shell is Bash, and it is available via the Terminal Utilities program within your Applications folder. To open Terminal, try one or both of the following:

  • Go to your Applications. Within Applications, open the Utilities folder. Locate Terminal in the Utilities folder and open it.
  • Use the Mac ‘Spotlight’ computer search function. Search for: Terminal and press Return.

For more info: How To use a terminal on Mac

Windows
Computers with Windows operating systems do not automatically have a Unix Shell program installed. We encourage you to use an emulator included in Git for Windows, which gives you access to both Bash shell commands and Git. To install, please follow these instructions.

X Windows System

Docker doesn’t have any build-in graphics, which means it cannot run desktop applications by default. For this, we require the X Windows System. The X Window System (X11, or simply X) is a windowing system for bitmap displays, common on Unix-like operating systems. X provides the basic framework for a GUI environment: drawing and moving windows on the display device and interacting with a mouse and a keyboard.

If you are on a desktop Linux, you already have one. For macOS, you can download XQuartz, and for Windows, we tested VcXsrv.

Desktop applications will run in Docker and will try to communicate with the X server you’re running on your PC. They don’t need to know anything but the location of the X server and an optional display that they target. This is denoted by an environmental variable named DISPLAY, with the following syntax: DISPLAY=xserver-host:0. The number you see after the : is the display number; for the intents and purpose of this article, we will consider this to be equivalent to 0 is the primary display attached to the X server.

In order to set up the environment variable, we need to add the following code to the docker run command in the terminal:

-e DISPLAY=host.docker.internal:0

-e DISPLAY=docker.for.mac.host.internal:0

--net=host -e DISPLAY=:0

With these commands (and an active X server on the host system), any graphical output inside the container will be shown on your own desktop.

Mount a volume

The docker image with which you can spawn a container contains all the software and general datafiles. However, we still need to give the container access to your dataset. To do so, we can mount a directory on your own system inside the container with the following command structure: -v <abs_path_host>:<abs_path_container>. Assuming your terminal is opened inside the data folder on your system, the specific commands for the different operating systems mount this folder as the /data folder inside the container, are:

For Windows in GitBash: -v /$(pwd):/data
For Windows in cmd: -v %cd%:/data
For Linux and macOS: -v $(pwd):/data

$(pwd) can be replaced with the absolute path of the datafolder, or be used to access subdirectories (e.g. $(pwd)/data:/data).

For more info about mounting volumes, check this StackOverflow question

Running a container with data and graphical output

To start a container from an image, we use the command docker run <image_name>. We also pass the additional flags --rm to delete the container after closing and -it to be able to interact with the container. Combining all arguments then leads to the following commands to run (and automatically close) the container:

docker run --rm -it -e DISPLAY=host.docker.internal:0 -v /$(pwd):/data <image_name>:<image_version>

docker run --rm -it -e DISPLAY=docker.for.mac.host.internal:0 -v $(pwd):/data <image_name>:<image_version>

docker run --rm -it --net=host -e DISPLAY=:0 -v $(pwd):/data <image_name>:<image_version>

Issues/Troubleshooting

  • For Linux users encountering the error Unable to init server, please run xhost + in the terminal and rerun the docker run command. For more info, see here.
  • WSL 2 installation incomplete for Windows users
    • Enable the virtualization in the BIOS
    • Follow ALL the steps described in: https://docs.microsoft.com/en-us/windows/wsl/install-manual
  • Failing to port a display in the docker container for Mac users.
    • Solution: Change the docker run command by this one , docker run --rm -it -e DISPLAY=IPADDRESS:0 -v $(pwd):/data <image_name>:<image_version>
    • The IPADDRESS is gotten from typing ifconfig in the terminal.
  • Failing to run the pipeline once the GUI is open
    • Check that all documents are closed before run it , namely the Getting started and the adapter files documents.
  • Failing to mount an external hard drive in Windows when running a docker container
    • Error:
          libGL error: No matching fbConfigs or visuals found
      libGL error: failed to load driver: swrast
    • Solution (noy yet found):
  • Look into this links:
    • https://stackoverflow.com/questions/46586013/glxgears-not-working-inside-of-docker