Docker Beginner Biologist 1
Docker Beginner Biologist 1
Docker Beginner Biologist 1
1 Learning objectives
2 Docker
3 Installation
4 Getting started
5 Review
6 Docker for (biologist) end-user
7 Background on Docker
8 Summary of commands learned
REFERENCES
1 Learning objectives
What is Docker
Images and Containers
Running a software withing a container
Shared directory
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.)
1.1 Requirements
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.)
file:///tmp/Docker_01.html 1/21
12/5/2019 Docker - Beginner Biologist 1
2 Docker
In the old days a docker could be a person working on the docks:
The Docker software is based on the Linux operating system and software running within
the container should be a Linux-based software, even though the container can run on all 3
platforms.
file:///tmp/Docker_01.html 2/21
12/5/2019 Docker - Beginner Biologist 1
This definition may not mean much to non-IT computer users… Additionally, most of the
tutorials are targeted towards computer and IT personel and often for large deployements.
However, biologists and other scientists can also benefit from Docker to run software that
is difficult to install, or only available on the Linux platform.
The goal of this tutorials series is to introduce Docker to biologists focusing on a single
software at a time.
This definition completely forgets us, biologists and other scientists as “end-users” of
software! However, Docker can provide solutions that are useful to those of us trying to use
a software that they have difficulty installing (on Mac/Windows) or that simply is only
available for Linux.
Recently I help someone trying to install/compile a software that had other requirements,
including the RNA folding algorithm of the Vienna package. After multiple frustrating days
of failed software compilations, missing libraries and other incompatibilities and missing
dependecies, in the end, Docker provided the only viable solution.
In simple terms, with the help of the Docker software, one creates a container: an isolated
section of the computer that contains everthing needed to run a software.
file:///tmp/Docker_01.html 3/21
12/5/2019 Docker - Beginner Biologist 1
The container is created from an image itself previously created from a list of
requirements (a plain text Docker file.) Fortunately there are many images that are pre-
made and downloadable from the Docker Hub.
3 Installation
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.5 Scroll down the page to find
the paragraph “Supported platforms” to find specific MacOS and Windows installers. It
may be necessary to create a free username (see Reqirements section above.)
4 Getting started
To get started we need to open a text terminal as detailed below. In class we’ll use a
Macintosh.
TASK:
Do one of the following:.
1. Find Power Shell e.g. using Windows search or Cortana. This will open a suitable
text-based terminal.
file:///tmp/Docker_01.html 4/21
12/5/2019 Docker - Beginner Biologist 1
If you are following this document in HTML format the code is shown with a colored
background:
docker --version
docker version
file:///tmp/Docker_01.html 5/21
12/5/2019 Docker - Beginner Biologist 1
In the same way the command docker info will provide a long list, here are the first 10
lines:
docker info
Client:
Debug Mode: false
Server:
Containers: 2
Running: 0
Paused: 0
Stopped: 2
Images: 10
Server Version: 19.03.5
TASK:
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
$
file:///tmp/Docker_01.html 6/21
12/5/2019 Docker - Beginner Biologist 1
docker:
Got permission denied while trying to connect to the Docker daemon s
ocket
at unix:///var/run/docker.sock:
Post http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/create:
dial unix /var/run/docker.sock: connect: permission denied.
See 'docker run --help'.
However, since we are going to use Docker, we’ll “pull” (i.e. copy automatically) a pre-
made Docker image that will run “ Hello World ” within a container and display this on
our screen.
docker : invoques the Docker software. All commands will start with docker .
run : Docker will run the following named item: a Docker image.
hello-world : name of a Docker image with informations to run a version of the
“ Hello World ” program.
Since this image is not (yet) on the local computer it will be “pulled” (copied) directly from
the docker hub web site: hence the need to register and login as a user.
“Running”" the image will create a temporary container, that in turn will run the
“ Hello World ” program. When the “ Hello World ” program has finished, the container
will stop. However, depending on the command structure, the container can remain active
for further use as we’ll see later.
TASK:
run commands.
file:///tmp/Docker_01.html 7/21
12/5/2019 Docker - Beginner Biologist 1
You will note that this runs immediately without the need to “pull” or download anything.
This also means that the Docker Image is now installed (copied) onto the local computer
disk. In order to list the images that are present we can use docker image ls where ls
is a listing sub-command.
docker image ls
file:///tmp/Docker_01.html 8/21
12/5/2019 Docker - Beginner Biologist 1
In the same way we can list the (running) containers with the command
docker container ls . However, since the hello-world container has finished its job
and stopped, we need to add the --all option:
NAME
trusting_fermi
Note that there are 2 more columns: PORTS is empty and pertains to more complex
situations (for example a web server running inside the Docker container.) The last column
NAMES contains an alternate name (here trusting_fermi ) that is made-up each time
from a dictionary of words, therefore you will have a different name. This can be useful
later to e.g. delete the container permanently. This is simply easier for humans, as the
name of the container is that more difficult to remember or type under the column
CONTAINER ID .
5 Review
So far we have tested if docker is functional and ran a quick first test with hello-world .
During this process we have already encountered some key elements:
file:///tmp/Docker_01.html 9/21
12/5/2019 Docker - Beginner Biologist 1
Also, for now we will only deal at first with text-only software that does not require
graphical interface.
Later, in a more advanced tutorial, we’ll learn how to create our own images.
Docker will create a container to run software that is first listed, like a cooking receipe, on
a Docker File, a plain text file. This file is later converted into an Image, that can be stored
locally or uploaded (and later downloaded again on another computer) on the Docker Hub.
The image can be as small as a few Kb, but can be as big as multiple Gb.
As end-user we will at first only use existing images that will be pulled from the Docker
Hub. These will be stored on the local computer once they are “pulled.”
The image will run and spawn a container once the docker run some-image command is
applied to the some-image image (stored or pulled.)
file:///tmp/Docker_01.html 10/21
12/5/2019 Docker - Beginner Biologist 1
There are then three main ways that we can use the software inside the container,
(and that in turn might also depend on how the image was created in the first place.)
To illustrate this we’ll use a very small Linux distribution called Alpine.
All hub pages show a pull command on the right hand side.
TASK:
get Alpine on your computer.
While the echo command actually also exists on a Mac Terminal, the one that will
actually be running will be the one inside the Alpine container.
We’ll have the words “hi there” typed on the screen. Note that in this case the quotes are
actually not mandatory, but here for better clarity.
TASK:
run commands.
hi there!
(Note: Single quotes above work. Double quote would give an error.)
To better convince ourselves that it is the container that is creating the output, we’ll as a
more “personal” question to Alpine in 2 forms: namely to tell us it’s name and versions
with commands cat /etc/os-release which will type on the screen the content of the
requested file, and uname -a which will provide a more generic answer. These will be
specific to the Alpine version that is installed and run within the container.
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.10.3
PRETTY_NAME="Alpine Linux v3.10"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://bugs.alpinelinux.org/"
We can also see a list of the now terminated container. Again the --all makes it show
containers that are no longer running.
file:///tmp/Docker_01.html 12/21
12/5/2019 Docker - Beginner Biologist 1
To accomplish this we can simply ask to run the shell command from within the container
by requesting /bin/sh .
However, this time we need to be “interactive” and we need to add in either form either
-it , -ti or -t -i to specify that we want an interactive ( -i ) terminal ( -t .)
TASK:
Run the following commands:
/ #
We are now executing command within the Linux Alpine terminal shell session!
We can try a few commands. This one will tell us what is our username:
/ # whoami
root
/ # ls
file:///tmp/Docker_01.html 13/21
12/5/2019 Docker - Beginner Biologist 1
As an exercise we’ll go inside the directory called home and create a simple text file.
Note: to exit the typing mode, it is necessary to issue a keyboard control CTRL + D
/ # cd home
/home # cat > Sample.txt
This text will exist inside the container.
But will not be saved when we exit.
[NEED CONTROL + D HERE TO EXIT TYPING]
/home #
/home # ls
Sample.txt
However, when we exit the container the file will be lost and not saved.
exit
Restarting the image will only create a new, blank container in the same state as we did the
first time: i.e. there was no Sample.txt file present.
You can try ls home and verify that the file is no longer there.
This is one way that Docker allows to “start fresh” each time the container is created from
the image.
file:///tmp/Docker_01.html 14/21
12/5/2019 Docker - Beginner Biologist 1
This is an advanced feature right here in a Beginner’s tutorial, but I think it will help clarify
some things and indeed could prove very useful for recovery.
When the image is activated again with the docker run command, it will create a new
container each time. When that container ends its job, it is in fact not destroyed but still
“lives” inside the computer in an idle form. We can list them with the command. We are
interested in the top 2: the one we just restarted, and the one before onto which we created
the file.
To make it simpler, it is best to note the names in the NAMES column. These will be
different for each one of you, but in any case is easier for a human brain than the
CONTAINER ID name.
docker container ls -a
Indeed if you made multiple attempts at the docker run commands you may have more
than 2. All you need to remember is which one was used when you created the
Sample.txt file. In my case it was kind_rhodes (or 2b33dfa50f02 .)
kind_rhodes
Step 2: run it as interactive terminal ( -it ) and attach a process to execute ( exec )
within it, here a shell ( sh ):
file:///tmp/Docker_01.html 15/21
12/5/2019 Docker - Beginner Biologist 1
/ #
/home # ls
Sample.txt
In the next section we’ll see how we can share a folder between the container and the local
computer to avoid loosing files and for an overall better access to data to and from within
the container.
--rm
There is a simple way to avoid having a heap pile of stopped containers by adding --rm to
remove (delete) the container once it stops running. For example:
Therefore, the container started above would be deleted when exiting (command: exit )
and this container would not appear in the list with command docker container ls -a
(see paragraph above.)
The container can be named with either the CONTAINER ID or its name under NAMES
found in the list given by docker container ls -a .
Continuing with the kind_rhodes example: (change to the name(s) of your idle
container(s).)
The best way to provide two-way exchange of files and data between the local computer
and the container is to share a directory.
This is accomplished by adding the qualifier -v and the path (location) of the directory to
be shared. The added command will have the form
-v /host/directory:/container/directory . Therefore we need to know two things:
On the local machine we can use an existing directory, or simply create a new one. For this
exercise we’ll create a new directory that we could call dockershare and for ease of use
we can place it onto the Desktop.
On the container it may be useful to explore what is available before makign a decision, as
each container will have a different organization within. For Alpine we already know that
/home is an empty directory when started fresh as we have explored above.
TASK:
Run the following commands:
Within the terminal we’ll nagigate to the default users directory a new directory on the
local machine:
cd
mkdir dockershare
file:///tmp/Docker_01.html 17/21
12/5/2019 Docker - Beginner Biologist 1
The first command ( cd ) takes us back to our user area. Then we move to the Desktop and
create a new directory with the mkdir (“make directory”) command. Of course, you could
create that directory also with the Macintosh graphical interface ahead of time.
cd dockershare
pwd
/Users/jsgro/dockershare
We’ll use the /home directory. For any other container it would be useful to explore its
content first.
Note: It is important to note that the content of the /home directory would be “masked”
i.e. not available while the folder inside the container is being shared.
We are now ready to open a new container and share the directory with the following
command:
Note that this command has -it to make it interactive, --rm to remove the container
when we exit, and -v to engage the shared folders. Then we specify the Alpine image and
ask for the shell to run within the container.
We are now sharing a directory with the local computer, that we can access via the /home
directory within the docker session. We can create a simple test file to verify that it will
remain after we are done with the docker container:
/ # pwd
cd home
cat > Test.txt
This file is created within the container
and should remain within the shared folder
once we are finished.
[NEED CONTROL + D HERE TO EXIT TYPING]
/home #
/home # exit
file:///tmp/Docker_01.html 18/21
12/5/2019 Docker - Beginner Biologist 1
If you now navigate to the the directory on the local machine you should see the file
Test.txt that was created within the container.
Variables to the rescue: rather than specifying the full path, we can use a variable
created “on the fly” that would contain the name of the current directory. Under bash this
is accomplished with $(pwd) . In this formula, pwd is executed first within the
parentheses and provides the name of the current directory. Then the $ implicitly makes
this a substitutable variable in a formula. Therefore the command could be given as follows
to use the current directory as the shared directory on the local machine:
Note: This variable is created “on the fly” but could be created in advance with the export
command.
Note for Windows users (in PowerShell ): In Windows the variable has to be created first
with the Windows command Get-Location (that works like pwd , which is also available
at least in PowerShell.) The other difference is the change from parenthesis () to curly
brackets {} . The Windows cascade of command would therefore be:
$loc = Get-Location
docker run -it -v ${loc}:/home alpine:latest /bin/sh
7 Background on Docker
An early paper by Boettiger (2014) describes using Docker for reproducible research.
An early article in Linux Journal describes the beginnings of Docker: Merkel (2014)
file:///tmp/Docker_01.html 19/21
12/5/2019 Docker - Beginner Biologist 1
Command Comment
docker run -it --rm -v $pwd:/home alpine /bin/sh run shell in container,
share current directory
REFERENCES
file:///tmp/Docker_01.html 20/21
12/5/2019 Docker - Beginner Biologist 1
Boettiger, Carl. 2014. “An Introduction to Docker for Reproducible Research, with
Examples from the R Environment.” Arxiv. https://arxiv.org/abs/1410.0846v1
(https://arxiv.org/abs/1410.0846v1).
Merkel, Dirk. 2014. “Docker: Lightweight Linux Containers for Consistent Development
and Deployment.” Linux Journal, March. https://dl.acm.org/citation.cfm?id=2600241
(https://dl.acm.org/citation.cfm?id=2600241).
1. https://en.wikipedia.org/wiki/Docker_(software)
(https://en.wikipedia.org/wiki/Docker_(software))
2. https://opensource.com/resources/what-docker
(https://opensource.com/resources/what-docker)
3. https://docs.docker.com/get-started/ (https://docs.docker.com/get-started/)
4. https://www.docker.com/resources/what-container
(https://www.docker.com/resources/what-container)
5. https://docs.docker.com/install/ (https://docs.docker.com/install/)
6. https://stackoverflow.com/questions/602237/where-does-hello-world-come-from
(https://stackoverflow.com/questions/602237/where-does-hello-world-come-
from)
7. https://docs.docker.com/get-started/ (https://docs.docker.com/get-started/)
8. https://alpinelinux.org/about/ (https://alpinelinux.org/about/)
file:///tmp/Docker_01.html 21/21