Skip to article frontmatterSkip to article content

Abstract

This guide will help you install Docker, pull and run the multi-architecture Docker image chungc/cs5483nb running JupyterLab, and use nbgitpuller to clone a GitHub repository into a specified subfolder.

A Docker container is like a lightweight, standalone, and executable package that includes everything needed to run a piece of software, including the Jupyter server used for our course. If you know about virtual machines, you may think of a docker container as a separate virtual machine running on your host machine, but with much less overhead. Indeed, you can also run the Jupyter server locally in your computer by installing Docker as follows.

Step 1: Install Docker

  1. Download and install Docker Desktop for your operating system from the official Docker website.
  2. Run the installer and follow the on-screen instructions. See the additional setup if you would like to use docker for WSL2 on Windows.
  3. Once installation is complete, open Docker Desktop and ensure it is running.

Step 2: Pull the Docker Image

Open a terminal (Command Prompt on Windows or Terminal on macOS) and run the following command to pull the Docker image:

docker pull chungc/cs5483nb

There is no need to pull the image again unless the image is updated.

What is a docker image?

A docker image is a the blueprint for creating Docker containers. When you run a Docker container, it is instantiated from an image. For example, chungc/cs5483nb is a docker image created from a text file Dockerfile.core, which specifies how and why packages should be installed. The image was built using some Make commands in the repository. The resulting image was published to the public registry DockerHub. You can also git clone the repository locally in your computer and modify the dockerfiles to build your desired image locally.

Step 3: Run the Docker Container

Navigate to your working directory (e.g., cs5483_home) where you want to map to the home directory of the docker container:

cd /part/to/cs5483_home

Run the Docker container with the following command:

docker run -it --rm \
  -p 8888:8888 \
  -v $(pwd):/home/jovyan/ \
  chungc/cs5483nb \
  start-notebook.sh \
  --IdentityProvider.token=''
Command options

This command will:

  • Run the container interactively (-it).
  • Remove the container after it stops (--rm).
  • Map port 8888 on your host to port 8888 on the container (-p 8888:8888).
  • Mount the current working directory to the home directory /home/jovyan/work inside the container (-v $(pwd):/home/jovyan/work).
  • Set the token to an empty string ('') so that you don’t need to provide a token when logging in (--IdentityProvider.token='').

See the documentation for other options.

By using the -p 8888:8888 option in the docker run command, you’re essentially creating a network bridge that allows you to access the service running inside the Docker container (JupyterLab on port 8888) from your host machine using http://localhost:8888. This port mapping facilitates communication between the host and the container while preserving the isolation and lightweight nature of Docker containers. If port 8888 is occupied in your host by other web apps, you may change it to another number such as 5483.

By mounting your current working director in the host with -v $(pwd):/home/jovyan/work, the files in the container is stored in the working directory in your host, meaning that they persist even after the container is removed.

Step 4: Access the JupyterLab and Notebooks

If successful, the following message will appear but with a different token or no tokens.

...
    To access the server, open this file in a browser:
        file:///home/jovyan/.local/share/jupyter/runtime/jpserver-7-open.html
    Or copy and paste one of these URLs:
        http://2d94aee27406:8888/lab?token=afe3d84a4cadff3fe397640f651de4805471e7b19d1d6f1e
        http://127.0.0.1:8888/lab?token=afe3d84a4cadff3fe397640f651de4805471e7b19d1d6f1e

Copy and paste the last URL into your web browser to login to the JupyterLab.

To access the course notebooks, open a new terminal within the JupyterLab interface and run the following command:

gitpuller https://github.com/dive4dec/cs5483_24b main cs5483_24b
Gitpuller command

This command will:

  • Pull the main branch of the GitHub repository dive4dec/cs5483_24b.
  • Clone it into the subfolder cs5483_24b under the mounted working directory work.

You may also use the git-pull link to open a specific notebook after git pulling:

http://127.0.0.1:8888/git-pull?repo=https%3A//github.com/dive4dec/cs5483_24b&urlpath=lab/tree/cs5483_24b/Tutorial1/

Project 2
Project 2