Use the Docker Images built on RenkuLab

Identify the name of the image you want to use

The easiest way to spin up your runtime environment locally is by pulling the image that has already been built.

First, make sure that your project has been pushed and that the image build is complete. If you are not sure, the easiest way to check is to navigate to your project in RenkuLab and go to launch a new session - if the “Start environment” button is available, it means the image has been built already.

To pull the image, you need to construct the image name. This is typically the format to expect: registry.<renku-host>/<namespace>/<project>:<commit-sha-7>. Lets break down the meaning of these terms in brackets:

renku-host is the hostname of the RenkuLab instance
namespace is either the username or the group name of the project owner
project is the project name
commit-sha-7 is the first 7 characters of your commit’s SHA

Let’s take the project https://renkulab.io/projects/rok.roskar/flights-tutorial.git as an example:

renku-host: renkulab.io
namespace: rok.roskar
project: flights-tutorial
commit-sha-7 of the latest commit can be retrieved by running:

$ git rev-parse origin/HEAD | cut -c 1-7

54dc19f

So the full name of this image, including the tag would be registry.renkulab.io/rok.roskar/flights-tutorial:54dc19f.

Alternatively, you can find all available images in GitLab’s Container Registry interface, e.g., https://renkulab.io/gitlab/rok.roskar/flights-tutorial/container_registry.

Launching the session locally

Finally, we can launch a session locally with the image that has been built for the chosen commit.

Note

If your project is private or internal, then you need to first login to the targeted registry:

$ docker login registry.renkulab.io

You will then be asked to enter your Username and Password:

Username is your username, e.g., rok.roskar
Password is your Personal Access Tokens with at least read_registry access, which can be created in GitLab, e.g., https://renkulab.io/gitlab/-/profile/personal_access_tokens

From the project’s root directory, run

$ imageName=registry.renkulab.io/rok.roskar/flights-tutorial:54dc19f
$ repoName=$(basename -s .git `git config --get remote.origin.url`)
$ docker run --rm -ti -v ${PWD}:/work/${repoName} \
  --workdir /work/${repoName} -p 8888:8888 \
  ${imageName} jupyter lab --ip=0.0.0.0

Replace imageName here with whatever image you derived for your project and commit above (or if you built your own image, the image/tag combo you used). This command instructs docker to run the image from the remote registry and to override its default command with jupyter lab. It also sets the port (-p flag), mounts the current directory into the container (-v) and sets that as the working directory (--workdir). Once the image downloads and the container is created, you will see a series of log messages ending in something like:

To access the notebook, open this file in a browser:
    file:///home/jovyan/.local/share/jupyter/runtime/nbserver-24-open.html
Or copy and paste one of these URLs:
    http://c1e432281137:8888/?token=616bc995658cb9f46673a8fcf486d5c0468f6c6058deb645
 or http://127.0.0.1:8888/?token=616bc995658cb9f46673a8fcf486d5c0468f6c6058deb645

To access the running environment, copy the last of these links (starting with https://127.0.0.1) into your browser and you should drop straight into the jupyter lab session. The rest should feel rather familiar - your environment should be identical to what you are used to seeing in your RenkuLab sessions.

In the jupyterlab session, you can change the URL end-point from /lab to /rstudio for RStudio projects, or /vnc for VNC projects.