Basic Docker usage on desktop Linux

The official docs are at https://docs.docker.com.

Installing on Ubuntu

Install the docker.io package:

sudo apt install docker.io

Add yourself to the docker group:

sudo usermod -aG docker $USER

Activate new groups by logging in to a new shell:

su $USER

Check that setup succeeded by installing a minimal test image:

docker run hello-world

Getting an image

To download an image:

docker pull ubuntu

This will download the latest image for the ubuntu repo on Docker Hub (i.e. the image with the latest tag, equivalent to docker pull ubuntu:latest).

For unofficial repos, the image name consists of {user_id}/{repo}, e.g. broadinstitute/gatk.

To use a specific version of an image (not the latest), append the version number or a different tag, e.g.

docker pull python:3.6-slim
docker pull broadinstitute/gatk:4.1.3.0

When pulling an image without specifying a registry, it will pull from Docker Hub. To pull from a different registry, use {registry_domain}/{project_id}/{repo}. E.g. to use the Google Container Registry when running GATK on the Google Cloud platform:

docker pull us.gcr.io/broad-gatk/gatk:4.1.3.0

docker pull ubuntu is equivalent to docker pull docker.io/ubuntu.

Note that you don’t need to manually download the image using pull: If you spin up a container using an image that isn’t locally available, it will be automatically pulled.

Running commands in a container

To spin up a new container for a given image and run a command inside it:

docker run ubuntu echo Hello!

ubuntu containers by default run /bin/bash if no other command is specified. However, this will exit immediately unless the -i and -t flags are also used so as to allocate an interactive terminal:

docker run -it ubuntu

Note that other images may specify a different default command. E.g. the python image runs python3 by default.

To show the currently running containers:

docker ps

To also show containers that were previously run but that have exited:

docker ps -a

A previously run container can be restarted by name (but reattaching will only work if it was previously started with -it):

docker start --attach {adjective_name}

To mount a directory on the local filesystem inside the container:

$ mkdir data
$ touch data/file.txt
$ docker run -v $PWD/data:/data ubuntu ls /data/
file.txt

Cleaning up containers & images

To delete the previously run containers:

docker ps -aq | xargs docker rm

To delete an image no longer used by any containers:

docker rmi $(docker images -q hello-world)