Interactive Environment Basics¶
What is an Interactive Environment?¶
Interactive environments on RenkuLab are web-based user interfaces (like JupyterLab and RStudio) that you can launch to develop and run your code and data workflows. They’re commonly used for exploratory analysis because you can try out short blocks of code before combining everything into a (reproducible) workflow.
You can run JupyterLab or RStudio within a project independently from RenkuLab, but RenkuLab offers the following advantages:
- environments hosted in the cloud with a configurable amount of resources (memory, CPU, and sometimes GPU)
- environments are defined using Docker, so they can be shared and reproducibly re-created
- auto-saving of work back to RenkuLab, so you can recover in the event of a crash
- a git client pre-configured with your credentials to easily push your changes back to the server
- the functionality provided by the renku-python command-line interface (CLI) is automatically available
What’s in my Interactive Environment?¶
- your project, which is cloned into the environment on startup
- your data (if the option
Automatically fetch LFS datais selected) files that are stored in git LFS*)
- all the software required to launch the environment and common tools for
working with code (
- any dependencies you specified via conda (requirements.txt), using
language-specific dependency-management facilities (
install.R, etc.) or installed in the
- the renku command-line interface renku-python.
- the amount of CPUs, memory, and (possibly) GPUs that you configured before launch
For adding or changing software installed into your project’s interactive environment, check out Customizing interactive environments
Which Interactive Environment will launch?¶
The template you choose when you create a project on RenkuLab (or locally call
renku init on your project) determines the kind of interactive environment
that is available to launch. Once it is initialized, your project can easily be
modified, for example to install additional libraries into the environment - see
Customizing interactive environments. We provide templates for basic Python, R, and Julia
projects. If you wish to use custom templates for your projects, you can build
your own! Please refer to the templating documentation.
Starting a new Interactive Environment¶
When starting a new interactive environment, you will be asked to configure it. The default configuration should work well for most situations. If, however, you encountered problems with an environment (for example, a crash), you might want to increase some processing power or memory. Here’s the rundown of the configuration options.
|branch||default master, but if you’re doing work on another branch, switch!|
default latest, but you can launch the environment from an earlier commit;
also useful if your latest commit’s build failed (see below).
|# CPUs||the number of CPUs available; resources are shared, so please select the lowest amount that will work for your use case.|
|memory||the amount of RAM available; resources are shared, so please select the lowest amount that will work for your use case.|
the number of GPUs available; You might have to wait for GPUs to free up in
order to be able to launch an environment.
|Automatically fetch LFS data||Leave off by default. If you find that workflows
you used to be able to run have stopped working,
check the contents of the file(s) – if plain text and contains
strings that are not your data, run
What if the Docker image is not available?¶
Interactive environments are backed by Docker images. When launching a new
interactive environment a container is created from the image that matches the
A GitLab’s CI/CD pipeline automatically builds a new image using the project’s
Dockerfile when any of the following happens:
- creating of a project
- forking a project (in which the new build happens for the fork)
- pushing changes to the project
(This is defined in the project’s
It can sometimes take some time to build an image for various reasons, but if you’ve just created the project on RenkuLab from one of the templates it should take less than a minute.
The Docker image is still building¶
If the Docker image has a “still building” message, you can either wait patiently,
or watch it build by clicking the associated link to see the streaming log messages
on GitLab. This can be useful if you’ve made changes to the
Dockerfile or added
install.R, where something
might have gone wrong.
The Docker image build failed¶
If this happens, it’s best to click the link to view the logs on GitLab so you can see what happened. Here are some common reasons for build failure:
- Software installation failure
problem You added a new software library to
install.R, but something was wrong with the installation (e.g. typo in
the name, extra dependencies required for the library but unavailable).
how to fix this
You can use the GitLab editor or clone your project locally to fix the installation,
possibly by adding the extra dependencies it asks for into the
(the commented out section in the file explains how to do this). As an alternative,
you can start an interactive environment from an earlier commit.
how to avoid this First try installing into your running interactive environment,
e.g. by running
pip install -r requirements.txt in the terminal on JupyterLab.
You might not have needed to install extra dependencies when installing on your
local machine, but the operating system (OS) defined in the
minimal dependencies to keep it lightweight.
- The build timed out
By default, image builds are configured to time out after an hour. If your build takes longer than that, you might want to check out the section on Customizing interactive environments interactive environments before increasing the timeout.
- Your project could not be cloned
If you accidentally added 100s of MBs or GBs of data to your repo and didn’t specify that it should be stored in git LFS, it might take too long to clone. In this case, read the docs on how to rewrite history and move these files into git LFS.
Another potential cause is if the project has submodules that are private.
The Docker image is not available¶
RenkuLab uses its internal instance of GitLab to build and store an image in the
registry each time you create a project, push changes, or use the RenkuLab UI to fork
a project. Thus, if you manage to get into a state that skips any of these steps,
the image might be unavailable. It’s a workaround, but the easiest way to get out
of this state is to manually trigger a build by adding a new trivial commit through
the GitLab instance, like editing the