Contents

Setting up docker

Setting up docker

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 (such as the SATAY GUI) 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 satay container

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 satay container:

docker run --rm -it -e DISPLAY=host.docker.internal:0 -v /$(pwd):/data leilaicruz/satay:latest 

docker run --rm -it -e DISPLAY=docker.for.mac.host.internal:0 -v $(pwd):/data leilaicruz/satay:latest 

docker run --rm -it --net=host -e DISPLAY=:0 -v $(pwd):/data leilaicruz/satay:latest

Access the terminal of the docker container

If you wish to inspect the content of the container interactively, add the command bash after the docker run. This will give you terminal access to the container.

docker run --rm -it -e DISPLAY=host.docker.internal:0 -v /$(pwd):/data leilaicruz/satay:latest bash

docker run --rm -it -e DISPLAY=docker.for.mac.host.internal:0 -v $(pwd):/data leilaicruz/satay:latest bash

docker run --rm -it --net=host -e DISPLAY=:0 -v $(pwd):/data leilaicruz/satay:latest bash

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

  • 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 leilaicruz/satay:latest

    • 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):

previous

SATAY pipeline

next

Creating a custom adapters.fa file