How to pin a docker image

Hi everyone, we have added some features recently that may not be directly obvious to everyone. These features allow users to select and fix (i.e. pin) the image that will be used to launch the Jupyterhub server(s). This way if the Docker image for your server does not change often or it takes a long time to build you can pin it so that you do not have to wait for the image to build on every commit.

This can be useful if you are sharing a project with many users who will fork it and not change the Docker image but just test out your code. It can be also useful for anyone who is using Renku to teach a class.

The easiest way to achieve this is as follows:

  1. Create a new renku project as usual, modify the Dockerfile as required, add code and allow gitlab to build the image. Skip this step if you already have an existing renku project.
  2. Go to the gitlab page of your project. This can be easily done by clicking the gitlab icon in the top right of the renkulab web page.
  3. On the gitlab project page navigate to Packages ā†’ Container Registry and find the docker image you would like to use and pin. Copy the path to this image using the little clipboard icon right next to the image name.
  4. Start a Jupyterhub session, and in the terminal run the command renku config set interactive.image "". Optionally you can also directly edit the image field in the .renku/renku.ini file in your project repository. If the image field does not exist in your renku.ini file then add it like so in a new line image = The safest and recommended way to do this however is to use the renku cli command and not edit the file directly.
  5. Optionally if you would like to prevent new docker images being built on every commit you can edit the file at the root of your repository and comment out the last two lines of the image_build step by adding a # sign at the beginning. If you have no other automated actions in the that you have added yourself you can also just fully remove this file. You can always look at a new renku project template or the history of your own repository to revert to the original file you started with.

With these changes even after adding new commits you will always use the same image and a new image will not be built on every new commit.

Here is an example public project which incorporates these changes if you are curious.


Hi ā€“ thank you for this, which would be really helpful.

I tried this for Renku and hit the following error:

$ renku config set interactive.image ""
Usage: renku config [OPTIONS] [KEY] [VALUE]
Try 'renku config -h' for help.

Error: Got unexpected extra argument (

Could this be related to the renku version Iā€™m running?

$ renku --version

@lgatto, yes your renku-cli version is too old to recognize that command.

If you want to update, the easiest way is to change this line in your dockerfile to read: RUN pipx install renku=='0.13.0' --force. Commit this, let the new image build, launch a new environment and you will be able to run the command you posted above successfully.

I launched a new session in your repo and updated renku to the latest version and the command succeeded. I only have view permissions to your repo (because it is public) so none of these changes I tested out persisted though.

1 Like

Thank you, worked as expected!