Summary and Setup
This session aims to introduce the use of Docker containers with the goal of using them to effect reproducible computational environments. Such environments are useful for ensuring reproducible research outputs, for example.
The practical work in this lesson is primarily aimed at using Docker on your own laptop. Beyond your laptop, software container technologies such as Docker can also be used in the cloud and on high performance computing (HPC) systems. Some of the material in this lesson will be applicable to those environments too.
Containers on HPC systems
On HPC systems it is more likely that Singularity rather than Docker will be the available container technology. If you are looking for a lesson on using Singularity containers (instead of Docker), see this lesson:
Prerequisites
- You should have basic familiarity with using a command shell, and
the lesson text will at times request that you “open a shell window”,
with an assumption that you know what this means.
- Under Linux or macOS it is assumed that you will access a
bash
shell (usually the default), using your Terminal application. - Under Windows, Powershell and Git Bash should allow you to use the
Unix instructions. We will also try to give command variants for Windows
cmd.exe
.
- Under Linux or macOS it is assumed that you will access a
- The lessons will sometimes request that you use a text editor to
create or edit files in particular directories. It is assumed that you
either have an editor that you know how to use that runs within the
working directory of your shell window (e.g.
nano
), or that if you use a graphical editor, that you can use it to read and write files into the working directory of your shell.
A note about Docker
Docker is a mature, robust and very widely used application. Nonetheless, it is still under extensive development. New versions are released regularly often containing a range of updates and new features.
While we do our best to ensure that this lesson remains up to date and the descriptions and outputs shown match what you will see on your own computer, inconsistencies can occur.
If you spot inconsistencies or encounter any problems, please do report them by [opening an issue][open a lesson issue] in the [GitHub repository][docker-introduction repository] for this lesson.
Requirements
- A Linux, Mac or Windows computer
- More than 5 GB free hard drive space
- If installing Docker yourself: root / administrator access
Warning
Docker uses root / administrator access for basic functionality. If installing Docker yourself, without root / administrator rights, it will not be possible to follow or complete this course.
If your computer has already been set up with Docker, then it may be possible to follow this course, please check locally.
Website accounts to create
Please seek help at the start of the lesson if you have not been able to establish a website account on:
- The Docker Hub. We will use the Docker Hub to download pre-built container images, and for you to upload and download container images that you create, as explained in the relevant lesson episodes.
Software to install
Installing Docker on different platforms requires different procedures and generally requires root / administrator access for a successful installation. Please follow the pointers below for assistance in finding the correct installation procedures.
Installation of Docker on Microsoft Windows comprises two central steps:
- Enabling the Windows Subsystem for Linux
- Installation of the Docker Desktop package
Microsoft publish a guide to installing WSL and Docker provide a guide for installing Docker Desktop.
Further, we provide some instruction here that attempts to unify these two guides.
- Confirm that you are running Windows 10, version 2004 or higher (Build 19041 and higher) or Windows 11.
Check your Windows version
To check your Windows version and build number, press the Windows
logo key + R, type winver
, select OK. You can
update to the latest Windows version by selecting “Start” >
“Settings” > “Windows Update” > “Check for updates”.
Open PowerShell as Administrator (“Start menu” > “PowerShell” > right-click > “Run as Administrator”) and paste the following commands followed by Enter to install WSL 2:
wsl --update
wsl --install --distribution Ubuntu
To ensure thatUbuntu
is the default subsystem instead ofdocker-desktop-*
, you may need to use:wsl --set-default Ubuntu
If you had previously installed WSL1 in Windows 10, upgrade to WSL2 with:wsl --set-version Ubuntu 2
Reboot your computer. Ubuntu will set itself up after the reboot. Wait for Ubuntu to ask for a UNIX username and password. After you provide that information and the command prompt appears, then the Ubuntu window can be closed.
Then continue to download Docker Desktop{:target=“_blank”}{:rel=“noopener noreferrer”} and run the installer.
Reboot after installing Docker Desktop.
Run Docker Desktop
Accept the terms and conditions, if prompted
Wait for Docker Desktop to finish starting
Skip the tutorial, if prompted
From the top menu choose “Settings” > “Resources” > “WSL Integration”
Under “Enable integration with additional distros” select “Ubuntu”
Close the Docker Desktop window
Warning: Git Bash
If you are using Git Bash as your terminal on Windows then you should be aware that you may run into issues running some of the commands in this lesson as Git Bash will automatically re-write any paths you specify at the command line into Windows versions of the paths and this will confuse the Docker container you are trying to use. For example, if you enter the command:
docker run alpine cat /etc/os-release
Git Bash will change the /etc/os-release
path to
C:\etc\os-release\
before passing the command to the Docker
container and the container will report an error. If you want to use Git
Bash then you can request that this path translation does not take place
by adding an extra /
to the start of the path. i.e. the
command would become:
docker run alpine cat //etc/os-release
This should suppress the path translation functionality in Git Bash.
Please install docker following these instructions.
Installation on Linux requires two steps:
- Installation of Docker Engine
- Enabling non-root access
Docker provide a guide to installing the Docker Engine which provides an overview of supported Linux distributions and pointers to relevant installation information.
Additionally, a generic installation option is provided using a convenience script.
Once the Docker Engine has been successfully installed, some post-installation steps must be taken.
Warning: Extra action if you install Docker using Snap
Snap is an app management system for linux - which is popular on Ubuntu and other systems. Docker is available via Snap - if you have installed it using this service you will need to take the following steps, to ensure docker will work properly.
These commands will let you use docker in the current terminal instance, but you will have to run “export TEMPDIR=~/tmp” in every new terminal you want to use docker in. An alternative is to append that command at the end of your bashrc file with
echo "export TEMPDIR=~/tmp" >> ~/bashrc
this will configure each new instance of a terminal to run that command at the start of every new terminal instance.
Verify Installation
To check if the Docker and client and server are working run the following command in a new terminal session:
OUTPUT
Client:
Version: 20.10.2
API version: 1.41
Go version: go1.13.8
Git commit: 20.10.2-0ubuntu2
Built: Tue Mar 2 05:52:27 2021
OS/Arch: linux/arm64
Context: default
Experimental: true
Server:
Engine:
Version: 20.10.2
API version: 1.41 (minimum version 1.12)
Go version: go1.13.8
Git commit: 20.10.2-0ubuntu2
Built: Tue Mar 2 05:45:16 2021
OS/Arch: linux/arm64
Experimental: false
containerd:
Version: 1.4.4-0ubuntu1
GitCommit:
runc:
Version: 1.0.0~rc95-0ubuntu1~21.04.1
GitCommit:
docker-init:
Version: 0.19.0
GitCommit:
If you see output similar to the above, you have a successful installation. It is important that both the “Client” and the “Server” sections return information. It is beyond the scope of this document to debug installation problems but some general advice would be to:
- double check the installation instructions for your platform
- ensure you have started a new terminal session (or rebooted your machine)