1 Learning objectives

Explore graphical options in specific docker images
Web-based options
X11 options

In class these exercises will be run onto the classroom iMacs.

However, as best as I can I’ll provide Windows hints and instructions when possible, but a basic understanding of line-command under Windows would be more than useful for that (e.g. know what is DOS for example. See APPENDIX C.)

1.1 Requirements

Be familiar with Docker or follow earlier workshops: “Docker - Beginner Biologist” workshops 1,2,3.
Docker will be used from a line-command terminal: Terminal on a Macintosh in the classroom. A rudimentary knowledge of bash command-line is necessary.
If you are a Windows user: PowerShell can be used as a Terminal. However, setting Docker to run on Windows is more involved (not covered in class.)
Docker username: downloads will require a (free) username, therefore registration is necessary in order to follow the tutorial. Go to https://hub.docker.com and use the button “Sign up for Docker Hub” to register.

2 Set-up

Tutorials will be held in the Biochemistry classroom 201, and Docker has already be installed.

Instruction for installation can be found on the install link¹ of the Docker web site.

Note HTML Version only:

If you are following this document in HTML format the code is shown with a colored background:

Green background: commands from local computer bash terminal

Ligh plum background: commands from ALTERNATE local computer bash terminal

White background: standard output of programs.

Blue background: commands and output when WITHIN a bash container

Yellow background: commands or output for information. Do not run!

2.1 Shared directory

We’ll use a shared directory called dockershare to share and save files.

Use mkdir $HOME/dockershare, see also Appendix A.

2.2 Getting started

To get started we need to open a text terminal as detailed below. In class we’ll use a Macintosh.

Do one of the following:.

If you are on a Macintosh:

Find the Terminal icon in the /Applications/Utilities directory. Then double-click on the icon and Terminal will open.
OR use the top-right icon that looks like a magnifying glass (Spotlight Search,) start typing the word Terminal and press return. Terminal will open.

If you are on a PC:

Find Power Shell e.g. using Windows search or Cortana. This will open a suitable text-based terminal.

(Note: Windows cmd does not offer the appropriate commands.)

2.3 Version check

This ensures that Docker is properly installed. The exact running version itself is not very important.

At the $ or > prompt within the window of Terminal or PowerShell type docker --version to check the version currently installed.

docker --version

Docker version 19.03.5, build 633a0ea

2.4 Docker login: Required!

Before going further, it is necessary now to login with your Docker Hub ID. You should already have created one before this or the previous workshop. If you need to create an ID now go to https://hub.docker.com to register.

Docker login:.

docker login

Login with your Docker ID to push and pull images from Docker Hub. 
If you don't have a Docker ID, head over to https://hub.docker.com 
to create one.
Username: YOUR_DOCKER_ID_HERE
Password: 
Login Succeeded
$

Note: if you do not login first you will receive an error message when trying to start docker in the next steps.

3 Choosing a docker image

Today’s workshop will be an exploration of docker images that provide a graphical interface, either web-based or X11-based. (The latter might not work easily on Windows.)

We’ll explore web-based and X11 examples which are the 2 major but very different graphical interfaces:

Web based:

NGINX web server
Dovex Python tool with web interface to explore datasets
R/RStudio web-based server version for the R interface

(For a quick overview see section "webapps with docker" online².)

X11-based:

X11 software IGV genome viewer
X11 utilities

3.1 Web-based images

In casual terms a container is running software on top of a host machine but without direct connection to the host files (unless a shared folder is specified) and without connections to the outside. In other words the container is almost like a box without a lid.

In simple terms, communication in and out the computer is done via specific “openings” called ports. For example, the port of an ssh connection is port 22. The default port for a web connection is port 80. A port is usually associated with a “protocol” which would be “Hypertext Transfer Protocol” or http for the web.

(For more details see Wikipedia links for “Port (computer networking)”³ and “well-known port numbers”⁴ )

This is important as we’ll have to know or specify (or both) which port are available for our purpose(s).

Note: The local computer is assigned a special web address which can be written in two equivalent ways:

localhost
127.0.0.1

3.2 X11 images

First of all this option is more “tricky” than the web options and might not work in all circumstances, and even less likely on a Windows computer. Hopefully the examples provided will prove useful.

Citing Wikipedia⁵: The X Window System(Scheifler and Gettys (1987)) (X11, or simply X) is a windowing system for bitmap displays, common on Unix-like operating systems.

4 Web server image

As a first exercise we’ll pull a docker image for a simple web server running over the linux implementation alpine seen in a previous workshop.

For this simple test we’ll use the official NGINX docker image. NGINX is open source software for web serving […].⁶

The docker hub page for this image is: https://hub.docker.com/_/nginx

The purpose of this container is to run a web server, and therefore it is likely that there will be some version of “entry point” (see previous workshop) that will start the web server as soon as the container is activated. This may be suggested from the information provided by the hub page.

The docker file is available online at https://github.com/nginxinc/docker-nginx/blob/master/stable/alpine-perl/Dockerfile and it ends with the following three statements, two of them will be useful later:

EXPOSE 80

STOPSIGNAL SIGTERM

CMD ["nginx", "-g", "daemon off;"]

The last line with CMD defines a default behavior when the container is started without specifying a command to be executed. In this case it would start the nginx web server, therefore not allowing shell access by default.

Note: CMD can be bypassed simply by adding a command at the end of a docker run command e.g. adding /bin/bash to open a shell.

In contrast an ENTRYPOINT command is mandatory and can only be bypassed by adding e.g. --entrypoint /bin/bash in the the docker run command.

For more on CMD and ENTRYPOINT see this blog entry⁷: “Docker RUN vs CMD vs ENTRYPOINT” - (lso archived at bit.ly/2WPDME2

pull NGIX image.

docker pull nginx

We can list images with:

docker image ls nginx*

REPOSITORY    TAG         IMAGE ID        CREATED         SIZE
nginx         latest      540a289bab6c    2 weeks ago     126MB

4.1 Docker run commands

In this section we’ll try a few versions for the docker run command to learn about opening and finding ports and other useful information.

There are many options that can be listed via command: docker run --help.

4.1.1 Random port mapping

In this first attempt we’ll use the -P modifier defined by help as:

-P, --publish-all Publish all exposed ports to random ports

This -P option will allow to map the ports, but as it is said in the help the mapping will be to a random number. We’ll detail below what that really means.

We’ll also introduce --name to provide a specific name designation of our choosing rather than a random name given to the container. This will help below to have a “standard” command for e.g. addressing the container. In other words, the commands will work for every user. The name chosen below is simply ng1.

Run command.

docker run --rm --name ng1 -P nginx

The $ terminal shell prompt is not reappearing, which means that the container is active. However, this terminal is no longer useable for anything else at the moment i.e. we cannot type any more commands, even addressed to the local host. Therefore it is necessary to open a new terminal for any command we want to issue on the local host.

Mac: use menu cascade Shell > New Window > Basic (or another colored option.)
Windows: open a new PowerShell

The docker run command above named the container ng1 and -P exposed the container ports to random port(s) on the host. We can find out what the random port is as shown below.

On the new terminal window type the following command using the name of the container:

 docker port ng1

80/tcp -> 0.0.0.0:32777

(Note: We could also see this information with docker ps under the PORTS column as shown below.)

In this example we see that port 80 which we saw earlier is the standard default port number for a web server is mapped to port 32777 which means that port 80 of the container would be connected to port 32777 on the local host (the computer you are using.)

Therefore you should be able to see the content of the web site in the container with the following web address with a web browser on your computer:

http://localhost:32777

Note: Adapt the port number to what you will see on your own terminal. The random aspect of -P means that the number on the local host might not be always the same. So we’ll fix this in the next section.

This is what you’ll see:

Summary: we were able to start a container running a web site and accessing the site from a browser running on the local computer.

We’ll see shortly that this can be very useful to run specific web-based software.

From this alternative terminal we can also see information about running containers with:

 docker ps

CONTAINER ID     IMAGE    COMMAND                  CREATED            STATUS           PORTS                     NAMES
bdadff9f3c9f    nginx     "nginx -g 'daemon of…"   24 minutes ago     Up 24 minutes    0.0.0.0:32777->80/tcp     ng1

The output is long an wraps, so it may be clearer to use the followiong command to only see the right-hand part:

docker ps | cut -c 105-150

  PORTS                   NAMES
  0.0.0.0:32768->80/tcp   ng1

Turn off container.

There are 2 ways to turn off this container:

“kill” the container process on the original terminal (green background in color version of this document) with Ctrl+C
“stop” the container with docker stop ng1. Since we started the container with --rm it will be automatically deleted when it is stopped.

4.1.2 Complete command

With this final, complete command we’ll address useful or necessary points.

Detached terminal: (-d) In the previous tests we had to use a secondary terminal because the prompt was not given back after launching the container. This can be changed and the container can be made to run in the background with the “detach” modifier as detailed in help: -d, --detach Run container in background and print container ID. -d will allow the shell prompt back, in effect placing the container processes in the background.
Name: (--name) as above we’ll specify a name of our choosing to designate the container. Here we’ll call it ng2.
Shared folder: (-v) this provides a channel of communication for data exchange between the container and the host file system. The folder /data will be created within the container and share all files from the dedicated host folder e.g. $HOME/dockershare. (See Appendix A.)
Port mapping: (-p) We’ll map the relevant port (port 80) to a port number of our own choosing with the -p (lower case) option.

From help:

-p, --publish list Publish a container's port(s) to the host.

Typical example mapped port names could be: 8080, 8787, 8888.

Start new, detached container with shared folder.

docker run -d --name ng2 -p 8080:80 --rm -v $HOME/dockershare:/data  nginx

aac92902b04e7819a35ab3abb0a2d485689fa980da37842b125c6bf251753f5d

Thanks to the -d flad we get the prompt back after the long name of the container is echoed on the screen. We can check the state of the container with the command: docker ps or docker container ls both providing the same output:

docker ps

CONTAINER ID   IMAGE     COMMAND                  CREATED           STATUS          PORTS                  NAMES
aac92902b04e   nginx     "nginx -g 'daemon of…"   3 minutes ago     Up 3 minutes    0.0.0.0:8080->80/tcp   ng2

We can note that the PORTS column contains 0.0.0.0:8080->80/tcp reflecting the port mapping.

We can now test if the web site works after opening a web browser to the local host address:

http://localhost:8080

Note that since we defined the port ourselves there is no randomness to this 8080 assignment.

EXERCISE:
Time permitting We can create a simple document and view it in the web browser.

Step 1: Create a simple document in the shared folder. (See Appendix A.) For example Copy/Paste the following to create a very simple HTML document (or create a file in a way you know how, or even a plain text file.)

cd $HOME/dockershare

cat > mytestfile.html <<- EOF
<h1>My Test</h1>
<p>This is a simple HTML file.</p>
EOF

Step 2: We’ll need access to a shell within the container. We can use the exec command that we learned in a previous workshsop. Since the container is detached we can use the same Terminal session with the command:

docker exec -it ng2  /bin/bash

root@aac92902b04e:/#

Therefore the next commands will be issued within the container.

Step 3: We need to know where the web site documents are stored. The nginx documentation is not so clear but the answer for this container is: /usr/share/nginx/html. Therefore we need to make our file mytestfile.html available at this location. One easy way is to simply copy it there, remembering that within the container the shared folder is called /data:

cd /usr/share/nginx/html
cp /data/mytestfile.html .
ls -l

(Note: If you are more familiar with bash an alternative would be to use a symbolic link (with ln -s) to the HTML file or a complete folder. This would be most useful for large size files, data files or folders.)

We can now check if this work within the web browser with the local web address:

http://localhost:8080/mytestfile.html

If all went according to plan, you should see this in your browser:

We can now exit the container bash session. This will return us to the local host $ prompt.

exit

Important Note: Since the container was created as detached the exit command here only takes us out of the exec session of bash initiated thereafter. Therefore the container is still running in the background, which is expected and wanted behavior. You can verify that this is true in 2 ways:

refresh the local host browser page: if the container was no longer running the page would become “not found” or an error such as “can’t connect to the server” may be shown.
run the docker ps command and see that the container is still active.

4.1.3 Stop container

Stop the container.

Now that we are done with this project we need to stop the container and delete it. Since we started the container with --rm when it is stopped it will be automatically removed. (Otherwise the docker rm command would be needed.)

docker stop ng2

ng2

Note: We can verify that this worked by checking with docker ps.

5 Dataset explorer: a Python tool

This next brief exercise is based on Dovex a web based tool to quickly provide an interactive overview and enable quick exploration of datasets from Melbourne Bioinformatics⁸ software collection.

The purpose of Dovex is to help inspect and explore tabular datasets in the form of summaries but also on a large number of optional graphical interactive plots.

Dovex has been tested on Python 3 and can be installed on the local computer. However, running or installing Python software should not be difficult, but it is often confusing. Running Dovex from a docker container will alleviate any necessary installation of Python on the local computer.

5.1 Docker image

pull dovex image. :latest is assumed.

docker pull supernifty/dovex