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:

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.