Introduction to Docker and Podman: Setup

Installation

The training module can be followed using either Docker or Podman. We recommend using Podman as it does not require root privileges to use it out of the box. In addition, Docker has licensing restrictions that may prevent you from using it in certain sites.

Installing Docker

If you prefer to use Docker (check with the IT department of your institution before using Docker!), follow the official instructions for Linux, Mac, or Windows.

If you are using Linux, then please also follow these post installation instructions.

Across the tutorial, just replace podman by docker in the commands and you should be good to go.

The installation of Podman requires sudo privileges. If you don’t have them, check if Podman is already installed on your system with:

podman version

If it’s not available, ask your system administrator to install it for you.

Install Podman on Linux

Podman is available on the official repositories of most Linux distributions. Check the official documentation to find out how to install it on your system.

For example, in Ubuntu, you can install it by running the following command:

# Ubuntu 20.10 and newer
sudo apt-get update
sudo apt-get -y install podman

Install Podman on MacOS

Running Podman or Docker on MacOS requires a virtual machine to run the containers. In the case of Podman, it provides an installer at https://podman.io/. Download the .dmg package for MacOS, extract it, and execute Podman Desktop.

The first time that Podman Desktop is executed it will be required to install Podman and a Podman machine to execute the containers. Click “Set up” and follow the instructions.

Install Podman on Windows

Podman provides instructions to install it on Windows at the GitHub repository.

Configuration

We will now configure Podman or Docker to download (pull) container images from the correct source.

If you do not have a CERN account, we will set things up so that images are pulled from Docker Hub (docker.io).

If you do have a CERN account, we will set things up to run from a CERN-hosted repository (registry.cern.ch/docker.io) instead. This is preferred, as there is a usage-limit for docker.io that can come into effect if multiple people are using it from the same IP address.

To use this CERN registry, regardless of if you use Podman or Docker, you will need to log in with

podman login registry.cern.ch
# or
docker login registry.cern.ch

It will then prompt you for a username and password. Use your CERN username. The password is the CLI token found at https://registry.cern.ch/ in your account under “User Profile”.

Podman

MacOS and Windows users

If you’re not on Linux, you will need to edit these configuration files from within the podman virtual linux machine. You can do this by connecting the the VM with

podman machine ssh

and editing the configuration files there.

Once you are done, exit the VM

exit

If you do not have a CERN account , add the following lines to /etc/containers/registries.conf to use docker.io.

# /etc/containers/registries.conf

unqualified-search-registries=["docker.io"]

If you have a CERN account, add these instead to use registry.cern.ch/docker.io

# /etc/containers/registries.conf

unqualified-search-registries=["docker.io"]

[[registry]]
prefix = "docker.io"
location = "registry.cern.ch/docker.io"

This will first set the default registry to docker.io, then it will map docker.io to registry.cern.ch/docker.io. This means that images pulled from registry.cern.ch/docker.io appear as if they’re coming from docker.io.

This mapping can have some unintended side effects, and so if it is causing any issues you can just clear the /etc/containers/registries.conf file and prepend registry.cern.ch/docker.io/ to image names manually as we show to do with Docker below. This is, however, more tedious than using the automatic mapping.

Docker

Docker uses docker.io by default.

If you are a CERN user and want/need to use the CERN registry, you can prepend registry.cern.ch/docker.io/ to each image name

So, for example, the command in the next section (with Docker) is

docker run hello-world

this will, by default, be equivalent to

docker run docker.io/hello-world

To pull from the CERN registry, you can instead do

docker run registry.cern.ch/docker.io/hello-world

after logging in, and similarly prepend registry.cern.ch/docker.io/ for all the commands in this tutorial.

Post Installation

Check that you can run Podman with the following command:

podman run hello-world

Optional: Fetch images in advance

Once you’ve got Podman up and running, do the following docker image pulls in advance to save time during the tutorial:

podman pull almalinux:9
podman pull debian:buster-slim
podman pull python:2.7-slim
podman pull python:3.7-slim

Analysis Code

Later in this tutorial, you will be asked to work with a simple analysis that utilizes the CMS OpenData to search for Higgs to 2 tau leptons. The full analysis itself can be found here — and there is a dedicated set of training lessons (videos available).

It is best if you work through these lessons before the tutorial on Containers, but not mandatory.