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.
  • 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.

  1. 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”.

  1. 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 that Ubuntu is the default subsystem instead of docker-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

  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.

  3. Then continue to download Docker Desktop{:target=“_blank”}{:rel=“noopener noreferrer”} and run the installer.

  4. Reboot after installing Docker Desktop.

  5. Run Docker Desktop

  6. Accept the terms and conditions, if prompted

  7. Wait for Docker Desktop to finish starting

  8. Skip the tutorial, if prompted

  9. From the top menu choose “Settings” > “Resources” > “WSL Integration”

  10. Under “Enable integration with additional distros” select “Ubuntu”

  11. 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.

BASH 

mkdir ~/tmp
export TMPDIR=~/tmp

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:

BASH 

$ docker version

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)