From bd2dfac8a18649b4691e9dd357939ccc01ea77f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rok=20Ro=C5=A1kar?= Date: Fri, 15 May 2026 16:31:49 +0200 Subject: [PATCH 1/2] docs: add docs for using renv in projects --- ...ironment-with-custom-packages-installed.md | 66 +++++++++++++------ ...custom-packages-private-code-repository.md | 22 +++++-- .../guides/00-environments/index.md | 23 ++++--- 3 files changed, 78 insertions(+), 33 deletions(-) diff --git a/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md b/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md index 8430f1e61e..0bcba0a11f 100755 --- a/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md +++ b/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md @@ -1,8 +1,11 @@ # Create an environment with custom packages installed -If you’d like a set of custom packages to be installed and ready to go when you (or anyone else) launches a session in your project, you can take advantage of Renku’s **code based environments**. +If you’d like a set of custom packages to be installed and ready to go when you (or anyone else) +launches a session in your project, you can take advantage of Renku’s **code based environments**. -With Renku code based environments, you can point Renku to a code repository that contains an environment definition file, such as a `environment.yml`, `requirements.txt`, or `pyproject.toml`, and Renku will build a custom environment for your session for you! +With Renku code based environments, you can point Renku to a code repository that contains an +environment definition file, such as an `environment.yml`, `requirements.txt`, `pyproject.toml`, or +`renv.lock`, and Renku will build a custom environment for your session for you! This guide has 2 parts: @@ -13,15 +16,7 @@ This guide has 2 parts: ## What kinds of environment definitions are supported? -RenkuLab’s code-based environments currently supports creating **Python** environments. Support for more languages is coming soon! - -:::tip - -Are you working in R? Support for R is coming soon. For now, for working with R please see -[installing packages on the fly in your -session](install-packages-on-the-fly-in-your-session). - -::: +RenkuLab’s code-based environments currently support creating **Python** and **R** environments. ### Defining a Python Environment @@ -144,13 +139,41 @@ Note that poetry version `1.8.3` will be used. -## Defining an R Environment +### Defining an R Environment with renv -:::info +Renku can build an R environment from an [`renv`](https://rstudio.github.io/renv/) lockfile. +`renv` records the R packages used by your project in `renv.lock`; Renku uses this lockfile to +restore those packages when building the session image. -This feature is coming soon. For now, please see [R](./install-packages-on-the-fly-in-your-session). ). +To use `renv` with a code-based environment: -::: +1. In your R project, install and initialize `renv` if you have not already done so: + + ```r + install.packages("renv") + renv::init() + ``` + +2. Install the packages your project needs as usual, for example: + + ```r + install.packages(c("dplyr", "ggplot2", "shiny")) + ``` + +3. Snapshot the environment to update the lockfile: + + ```r + renv::snapshot() + ``` + +4. Commit `renv.lock` at the root (top level) of the code repository. You should also commit the + files created by `renv` that are meant to be shared with the project, such as `.Rprofile` and + `renv/activate.R`. + +When Renku builds the image, it restores the packages recorded in `renv.lock`. If a package requires +system libraries that are not available in the build image, the build can fail. In that case, +consider using a custom Docker image instead; see [How to use your own docker image for a Renku +session](use-your-own-docker-image-for-renku-session). ## How to create a code-based environment for your Renku session @@ -162,7 +185,8 @@ repository](create-environment-with-custom-packages-private-code-repository). ::: -1. Make sure the code repository that contains your environment definition file is added to your Renku project. +1. Make sure the code repository that contains your environment definition file is added to your + Renku project. 2. Create a **new session launcher** 3. Select the **Create from code** option @@ -184,8 +208,10 @@ repository](create-environment-with-custom-packages-private-code-repository). ::: -5. Select the **Environment** **type** (Python, _more coming soon_) -6. Select the **User interface** you’d like your session to have (VSCodium or Jupyterlab, _more coming soon_). +5. Select the **Environment type**. Choose **Python** for Python environment definition files, + or **R** for repositories that use `renv.lock`. +6. Select the **User interface** you’d like your session to have, such as VSCodium/JupyterLab + for Python environments or RStudio for R environments. 7. Click **Next** 8. Define the **name** of the Session Launcher 9. Select the default **compute resources** @@ -199,7 +225,9 @@ When the environment is built, you can launch your session. ## Updating a code-based environment -1. When you want to make changes to your environment (add new packages), first update the environment definition file in the code repository where the environment is defined. +1. When you want to make changes to your environment (add new packages), first + update the environment definition file in the code repository where the + environment is defined. 2. Then, rebuild the environment in RenkuLab: 1. Click on the session launcher to open the session launcher side panel. 2. Navigate to the **Session Environment** section. diff --git a/docs/docs/10-users/60-sessions/guides/00-environments/25-create-environment-with-custom-packages-private-code-repository.md b/docs/docs/10-users/60-sessions/guides/00-environments/25-create-environment-with-custom-packages-private-code-repository.md index ce8adf659a..2563aa9105 100755 --- a/docs/docs/10-users/60-sessions/guides/00-environments/25-create-environment-with-custom-packages-private-code-repository.md +++ b/docs/docs/10-users/60-sessions/guides/00-environments/25-create-environment-with-custom-packages-private-code-repository.md @@ -1,14 +1,22 @@ # Create an environment with custom packages from a private code repository (GitHub Actions) -Would you like Renku to create an environment for you with the packages you need pre-installed? Renku can create a docker image for your Renku session for you based on a environment definition file in a code repository, such as a `environment.yml`, `requirements.txt`, or `pyproject.toml`. +Would you like Renku to create an environment for you with the packages you need pre-installed? +Renku can create a docker image for your Renku session for you based on an environment definition +file in a code repository, such as an `environment.yml`, `requirements.txt`, `pyproject.toml`, or +`renv.lock`. -If your code repository is public, you can have Renku build this image directly as part of your project! See [How to create an environment with custom packages installed](create-environment-with-custom-packages-installed). +If your code repository is public, you can have Renku build this image directly as part of your +project! See [How to create an environment with custom packages +installed](create-environment-with-custom-packages-installed). -If your code repository is private, follow the instructions below. +The instructions below are for _private_ code repositories that cannot use the +automatic builds in RenkuLab. ## Create a GitHub action to build a docker image -1. First, make sure your code repository meets the requirements for Renku to build an image for you. See [What kinds of environment definitions are supported?](create-environment-with-custom-packages-installed) +1. First, make sure your code repository meets the requirements for Renku to build an image for you. + See [What kinds of environment definitions are + supported?](create-environment-with-custom-packages-installed) 2. In your GitHub code repository, in the upper menu, click on **Actions**.

@@ -69,10 +77,14 @@ If your code repository is private, follow the instructions below. frontend: jupyterlab ``` -6. By default, the action defined above will create an image with JupyterLab as the front end. If you prefer a different front end, replace `jupyterlab` in the last line of the file with one of the following alternative front ends: +6. By default, the action defined above will create an image with JupyterLab as + the front end. If you prefer a different front end, replace `jupyterlab` in + the last line of the file with one of the following alternative front ends: - `jupyterlab`: Web-based interactive development for Jupyter notebooks, code, and data. - `vscodium`: A freely-licensed version of Microsoft’s editor VS Code. - `ttyd`: A web-based terminal with a minimalist interface. + - `rstudio`: RStudio Server for R projects. + 7. Commit changes ## Add the built image to your Renku project diff --git a/docs/docs/10-users/60-sessions/guides/00-environments/index.md b/docs/docs/10-users/60-sessions/guides/00-environments/index.md index 51c51f672f..606e6dffb0 100755 --- a/docs/docs/10-users/60-sessions/guides/00-environments/index.md +++ b/docs/docs/10-users/60-sessions/guides/00-environments/index.md @@ -20,13 +20,6 @@ environment is right for you, answer the following questions: ### 1. What language are you working in? -#### → I’m working in R - -Renku only has one mode for working with R sessions at the moment. When you create a session -launcher, select **global environment** and select the **R** global environment. If you need to -install additional packages, see [How to install packages on-the-fly in your -session](install-packages-on-the-fly-in-your-session). - #### → I’m working in Python We have multiple ways of working in Python in Renku sessions! Please continue to the next question @@ -34,6 +27,18 @@ We have multiple ways of working in Python in Renku sessions! Please continue to the session?](#2-would-you-like-packages-to-be-pre-installed-and-ready-to-go-when-you-or-anyone-else-launches-the-session). +#### → I’m working in R + +If your project uses [`renv`](https://rstudio.github.io/renv/) and has an `renv.lock` file, +Renku can build a code-based environment with your packages pre-installed. See [How to create an +environment with custom packages +installed](create-environment-with-custom-packages-installed#defining-an-r-environment-with-renv). + +If you do not need packages pre-installed, create a session launcher with a **global environment** +and select the **R** global environment. If you need to install additional packages temporarily, see +[How to install packages on-the-fly in your +session](install-packages-on-the-fly-in-your-session). + #### → I’m working in another language Working in some other language? That’s ok! You can run a wide variety of Docker images in Renku @@ -48,8 +53,8 @@ If you’d like a set of custom packages to be installed and ready to go when yo launches a session in your project, you can take advantage of Renku’s code based environments. With Renku code based environments, you can point Renku to a code repository that contains an -environment definition file, such as a environment.yml, requirements.txt, or pyproject.toml, and -Renku will build a custom environment for your session for you! +environment definition file, such as `environment.yml`, `requirements.txt`, `pyproject.toml`, or +`renv.lock`, and Renku will build a custom environment for your session for you! → If your code repository is **public**, see [How to create an environment with custom packages installed](create-environment-with-custom-packages-installed). From 7a2bbdd5f67984eeb8d9905e769abda778af7cf7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rok=20Ro=C5=A1kar?= Date: Wed, 20 May 2026 10:16:04 +0200 Subject: [PATCH 2/2] chore: add blurb about snapshot behavior --- ...environment-with-custom-packages-installed.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md b/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md index 0bcba0a11f..71ea28c169 100755 --- a/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md +++ b/docs/docs/10-users/60-sessions/guides/00-environments/20-create-environment-with-custom-packages-installed.md @@ -157,16 +157,26 @@ To use `renv` with a code-based environment: 2. Install the packages your project needs as usual, for example: ```r - install.packages(c("dplyr", "ggplot2", "shiny")) + install.packages(c("dplyr", "ggplot2")) ``` -3. Snapshot the environment to update the lockfile: +3. Write your analysis code that uses those packages. + +4. Snapshot the environment to update the lockfile: ```r renv::snapshot() ``` -4. Commit `renv.lock` at the root (top level) of the code repository. You should also commit the + :::warning + + The `renv::snapshot()` command will pick up only the packages that are + installed _and_ used in your source code. If you install packages but do not use them (yet) + they will not be added by default. + + ::: + +5. Commit `renv.lock` at the root (top level) of the code repository. You should also commit the files created by `renv` that are meant to be shared with the project, such as `.Rprofile` and `renv/activate.R`.