Get started#

This tutorial guides you through installing repo2docker and building your first environment image.

Prerequisite#

Python#

repo2docker requires Python 3.6 or above.

Container Engine#

repo2docker requires a container engine compatible with the specification published by the Open Container Initiative.

Docker#

Important

Only the Docker Engine is open source. Docker Desktop requires a license.

Follow Docker’s official installation steps.

Podman#

Follow Podman’s official installation steps.

After completing the installation of Podman,

  1. create a listening service for Podman by running

    systemctl --user start podman.socket

  2. configure the DOCKER_HOST environment variable following Podman’s official procedure. You might want to configure the DOCKER_HOST environment variable to persist in your ~/.bashrc.

Install repo2docker#

Install repo2docker with pip#

It is recommend to install repo2docker with the pip tool:

python3 -m pip install jupyter-repo2docker

Build a repository with repo2docker#

Now that you’ve installed a container engine and repo2docker, you can build a repository. To do so, continue following this guide.

Start the container engine#

Ensure that the container engine is running.

Docker#

Follow the offcial instructions for starting Docker.

Podman#

Run

podman info

Build an image from a URL#

Next we’ll build a reproducible image from a URL. We’ll use the Binder requirements.txt example, which installs a simple Python environment. Run the following command:

jupyter-repo2docker https://github.com/binder-examples/requirements

You’ll see repo2docker take the following actions:

  1. Inspect the repository for configuration files. It will detect the requirements.txt file in the repository.

  2. Build a container image using the configuration files. In this case, the requirements.txt file will correspond to a Python environment.

  3. Run the image to let you explore the repository interactively.

Click the link provided and you’ll be taken to an interactive Jupyter Notebook interface where you can run commands interactively inside the environment.

Learn more#

This is a simple example building an environment image for your repository. To learn more about the kinds of source repositories, environments, and use-cases that repo2docker supports, see the repo2docker user guide.