Docker	Documentation	GitLab

Status

version	base	minimal	scipy	datascience	rll1	mll2
CUDA 11.3.1
SYSTEM All automated tests are run on Linux (Ubuntu 20.04 Focal Fossa). Windows and Mac work with appropriate configurations, see installation section.			rll:= reinforcement learning lab mll:= machine learning lab

---

Welcome to the Machine Learning Lab repository! This repository is based heavily on the fantastic work being done at the jupyter/docker-stacks repository, if you haven't checked it out please do and support the work being done there. In this repository we include both cuda-enabled versions of a select number of images from the docker-stacks repository as well as some custom images not found there. If you would like to add images to this repository, we welcome that - just open a pull request! We plan to include a contribute.md soon that will outline how contributions should be made!

0. Table of Contents

1. Image Hierarchy
2. Usage Instructions
   1. Installation

1. Image Hierarchy

The current heirarchy of images can be found below. A description of each image can be found in the docs folder. The docs folder contains auto-generated documentation that is updated on every build to ensure always up-to-date information about each image. Feel free to use any of the images found in this repository as a base for your own custom images. I will keep these images updated regularly from the upstream repositories.

click to reveal image hierachy diagram

2. Usage Instructions

In this section we will discuss how we intend these images to be ran as well as how to install the required components on the host machine.

The easiest way to use any of the images is to modify the included docker-compose.yml and run docker-compose up to start Jupyterlab. For instance an example docker-compose.yml would be:

version: "3.8"

services:
  machine_learning_lab:
    image: IMAGE_NAME
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    ports:
      - 8888:8888
    environment:
      - JUPYTER_ENABLE_LAB=1
    volumes:
      - data:data:rw
      - results:results:rw

In this example docker-compose.yml, you would replace IMAGE_NAME with the name of whatever image you wish to run. For instance: samuel62/machine_learning_lab:datascience_cuda_11.3.1

Since most users of the images found in this repository are data scientists, we recommend binding a volume from your host machine to the container in the volumes section. Typically, you would include a data and a results folder in this section as well as any other directories you want the container to be able to read/write from on your host machine.

If you are not using a machine with a dedicated Nvidia GPU then comment/remove the deploy section as it will cause an error.

It is not necessary to use docker-compose to run the containers. Instead you could run them with the docker run command, e.g.:

docker run -p 8888:8888 -e JUPYTER_ENABLE_LAB=1 -v data:data:ro -v results:results:rw samuel62/machine_learning_lab:datascience_cuda_11.3.1

or

docker run \
    -p 8888:8888 \
    -e JUPYTER_ENABLE_LAB=1 \
    -v data:data:ro \
    -v results:results:rw \
    samuel62/machine_learning_lab:datascience_cuda_11.3.1

We recommend using the docker-compose method as it allows for more control without atrocious syntax.

2.1 Installation

Linux Instructions

reveal Linux instructions

There are two requirements on Linux and one optional command. The first is docker which we will show how to install for Debian (which includes Ubuntu) based distributions.

---

  ___          _           
 |   \ ___  __| |_____ _ _ 
 | |) / _ \/ _| / / -_) '_|
 |___/\___/\__|_\_\___|_|  
                           

If you don't know what docker is, please read this for more information: Docker overview

There are two ways to install Docker on Linux: one is from a convenience script and the other is manually. We will demonstrate both.

Convenience Scipt
The convenience script will attempt to install the most recent version of Docker on your machine. All that you need to do is curl the script and execute it using root privileges.

curl -fsSL https://get.docker.com -o get-docker.sh
DRY_RUN=1 sh ./get-docker.sh

Manual Installation
The instructions below come from the official Docker installation instructions for Ubuntu found here: official instructions

Check for old installations
First we need to check for any current docker installations and remove them. If you are installing on a new Linux install, then skip this section. Otherwise it is recommended to run the following command:

sudo apt-get remove docker docker-engine docker.io containerd runc

If apt-get reports that none of those packages are installed, that is OK and you can continue.

Pre-requisites
Update the apt package index:

sudo apt-get update

Install the following packages to allow apt to use https:

sudo apt-get install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

To install docker using apt-get we will need to add the docker gpg-key to sources.list. For security we can't install any packages that haven't been signed.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

After adding the gpg-key we can now install the docker-engine. First we will update the apt package list again.

sudo apt-get update

Now we can install the most current version of the docker-engine:

sudo apt-get install docker-ce docker-ce-cli containerd.io

Post installation steps
This section is optional but recommended. Once you have installed Docker on your machine you will be required to run any docker commands as the root using sudo. This is inconvenient among other things and hence adding the current user to the docker group is advised. Follow the steps in this section to add yourself to the docker group.

First we must create the docker group:

sudo groupadd docker

Now add yourself to the group:

sudo usermod -aG docker $USER

Finally run the follwoing command to activate the changes to groups:

newgrp docker

With all of the above complete you are finished installing Docker! You can test your installation by running docker info or docker run hello-world.

---

  _  ___   _____ ___ ___   _      ___ _____ _  __
 | \| \ \ / /_ _|   \_ _| /_\    / __|_   _| |/ /
 | .` |\ V / | || |) | | / _ \  | (__  | | | ' < 
 |_|\_| \_/ |___|___/___/_/ \_\  \___| |_| |_|\_\
                                                 

NOTE: This section is only relevant for those intending to run the images with GPU support. If your host machine does not have a dedicated NVIDIA GPU then skip this section and remember to run the images without the --gpus all flag or the deploy section if using docker-compose

The following information is summarized from the offical guide, please refer to the official guide for clarification on any of the below steps.

There are a few pre-installation steps we must take before installing the container toolkit.

• Verify the system has a CUDA-capable GPU.
• Verify the system is running a supported version of Linux.
• Verify the system has gcc installed.
• Verify the system has the correct kernel headers and development packages installed.
• Download the NVIDIA CUDA Toolkit.
• Handle conflicting installation methods.

To verify that the system has a CUDA-capable GPU run

lspci | grep -i nvidia

Make sure a CUDA-capable GPU is listed in the output. If not stop. If you believe there is an error and your GPU is not found then, update the PCI hardware database using update-pciids and try the above command again.

To verify that the system is running a support distribution run

uname -m && cat /etc/*release

and check the below table to make sure your distribution is supported. If it isn't then either skip this section or install one of the supported distributions.

---

click to reveal supported distributions

Table 1. Native Linux Distribution Support in CUDA 11.5

Distribution	Kernel1	Default GCC	GLIBC	GCC2,3	ICC3	NVHPC3	XLC3	CLANG	Arm C/C++
x86_64
RHEL 8.y (y <= 4)	4.18.0-305	8.4.1	2.28	11	2021	21.7	NO	12	NO
CentOS 8.y (y <= 4)	4.18.0-305	8.4.1	2.28
RHEL 7.y (y <= 9)	3.10.0-1160	6.x	2.17
CentOS 7.y (y <= 9)	3.10.0-1160	6.x	2.17
OpenSUSE Leap 15.y (y <= 3)	5.3.18-57	7.5.0	2.31
SUSE SLES 15.y (y <= 3)	5.3.18-57	7.5.0	2.31
Ubuntu 20.04.3	5.11.0-27	9.3.0	2.31
Ubuntu 18.04.z (z <= 6)	5.4.0-89	7.5.0	2.27
Debian 11.1	5.10.0-9	10.2.1	2.31
Fedora 34	5.11	11	2.33
Arm64 sbsa
RHEL 8.4	4.18.0-305	8.4.1	2.28	11	NO	21.7	NO	12	21.0
SUSE SLES 15.y (y <= 3)	5.3.18-57	7.5.0	2.31
Ubuntu 20.04.3	5.4.0-86	9.3.0	2.31
Arm64 Jetson
Ubuntu 18.04.z (z <= 6)	4.9.253	7.5.0	2.27	10.2	NO	21.7	16.1.x	12	NO
POWER 9
RHEL 8.y (y <= 4)	4.18.0-240	8.3.1	2.28	11	NO	21.7	16.1.x	12	NO

---

To verify that your system has gcc installed, run

gcc --version

If an error message is returned then please install gcc and its accompanying toolchain. On Ubuntu this can be achieved by running

sudo apt install build-essential

To check what verion of the kernel headers you have, run

uname -r

Cross reference the returned value with the one listed for your distribution in the above table. If you need to update your kernel headers follow the below instructions:

If you are running Ubuntu and need to install the newest kernel headers, run

sudo apt-get install linux-headers-$(uname -r)

for all other distributions refer to official guide for the appropriate commands.

*** Install CTK ***

Now we can install the NVIDIA CUDA Toolkit. The toolkit comes with everything needed to run CUDA applications, including drivers, header files, etc.. We will need this to run cuda-enabled images.

Follow the instructions here for your platform: https://developer.nvidia.com/cuda-downloads

---

  ___          _                ___                             
 |   \ ___  __| |_____ _ _ ___ / __|___ _ __  _ __  ___ ___ ___ 
 | |) / _ \/ _| / / -_) '_|___| (__/ _ \ '  \| '_ \/ _ (_-</ -_)
 |___/\___/\__|_\_\___|_|      \___\___/_|_|_| .__/\___/__/\___|
                                             |_|                

This section is optional as you can run any of the images without using docker-compose. We recommend installing docker-compose as it makes configuring the container much easier and allows for complex docker setups.

We can curl the binary directly into the bin directory:

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Now apply executable permissions to the binary:

sudo chmod +x /usr/local/bin/docker-compose

---

This completes the pre-requisites to run the images in this repository.

---