(docs) Simplify environment documentation

docs/docs/10-users/10-users.md

@@ -31,7 +31,7 @@ where all your project components work together.
 
 Renku is a platform for collaborative data science developed at the [Swiss Data Science Center](https://www.datascience.ch). It enables researchers to build collaborative projects that bring together [data](data/data), [code](code/code-repository), and [compute resources](sessions/session-launcher) from a variety of sources.
 
-Rather than hosting all these resources itself, Renku is a connecting hub that provides the means to bring them all together. For example, a project might use a published dataset from [Zenodo](https://www.notion.so/How-to-connect-data-from-data-repositories-such-as-Zenodo-or-Dataverse-1eb0df2efafc802ab3bef1c47c8c45b4?pvs=21), raw data from a shared [cloud storage resource](data/data) and code from a [GitHub repository](code/guides/add-code-repository-to-project). These are then made seamlessly available in containerized browser-based compute [sessions](sessions/session). Renku sessions can run on Renku servers or on an external computational resources such as a local cloud provider or - coming soon! - an HPC cluster. The sessions can be used for development with [environments](sessions/guides/add-session-launcher-to-project) like VSCode, Jupyter, or RStudio, or they can be used to display dashboards with Streamlit or Shiny. To promote sustainable computational research, Renku also makes it straightforward to build Docker images based on users' [software requirements](sessions/guides/create-environment-with-custom-packages-installed), ensuring that everyone using a project does so with the right software stack.
+Rather than hosting all these resources itself, Renku is a connecting hub that provides the means to bring them all together. For example, a project might use a published dataset from [Zenodo](https://www.notion.so/How-to-connect-data-from-data-repositories-such-as-Zenodo-or-Dataverse-1eb0df2efafc802ab3bef1c47c8c45b4?pvs=21), raw data from a shared [cloud storage resource](data/data) and code from a [GitHub repository](code/guides/add-code-repository-to-project). These are then made seamlessly available in containerized browser-based compute [sessions](sessions/session). Renku sessions can run on Renku servers or on an external computational resources such as a local cloud provider or - coming soon! - an HPC cluster. The sessions can be used for development with [environments](sessions/guides/environments/) like VSCode, Jupyter, or RStudio, or they can be used to display dashboards with Streamlit or Shiny. To promote sustainable computational research, Renku also makes it straightforward to build Docker images based on users' [software requirements](sessions/guides/environments/create-environment-with-custom-packages-installed), ensuring that everyone using a project does so with the right software stack.
 
 Collaborate on a fully reproducible Renku project by adding project [members](collaboration/guides/add-people-to-project), and showcase interactive demos and apps with anyone via [public session launch links](sessions/guides/share-session-launch-link). For larger collaborations, users can organize projects and other assets under [groups](use-cases/groups), which helps streamline collaboration.
 

docs/docs/10-users/20-getting-started/50-launch-session.md

@@ -35,7 +35,7 @@ We have set up a global environment which already has many packages installed. I
 
 :::info
 
-For a detailed guide for how to install packages, see [How to install packages in your session](../sessions/guides/install-packages-on-the-fly-in-your-session).
+For a detailed guide for how to install packages, see [How to install packages in your session](../sessions/guides/environments/install-packages-on-the-fly-in-your-session).
 
 :::
 

docs/docs/10-users/20-getting-started/_01-full-tutorial.md

@@ -115,7 +115,7 @@ We have set up a global environment which already has many packages installed. I
 
 :::info
 
-For a detailed guide for how to install packages, see [How to install packages in your session](/docs/users/sessions/guides/install-packages-on-the-fly-in-your-session).
+For a detailed guide for how to install packages, see [How to install packages in your session](/docs/users/sessions/guides/environments/install-packages-on-the-fly-in-your-session).
 
 :::
 

docs/docs/10-users/30-projects/guides/10-create-a-project.md

@@ -25,8 +25,8 @@ To create a new project:
 4. Add code repository as explained in [How to add a code repository to your project](../../code/guides/add-code-repository-to-project).
 5. Create a session launcher for working in your project:
     1. Select an environment:
-        1. Check out the environments available in Renku via [How to add a session launcher to your project](../../sessions/guides/add-session-launcher-to-project). If these are sufficient for your project, use them!
-        2. If you need to customize the environment for your project, you can create a custom environment yourself via [How to use your own docker image for a Renku session](../../sessions/guides/use-your-own-docker-image-for-renku-session), or  [Contact](../../community) us if you are in trouble!
+        1. Check out the environments available in Renku via [How to add a session launcher to your project](../../sessions/guides/environments/). If these are sufficient for your project, use them!
+        2. If you need to customize the environment for your project, you can create a custom environment yourself via [How to use your own docker image for a Renku session](../../sessions/guides/environments/use-your-own-docker-image-for-renku-session), or  [Contact](../../community) us if you are in trouble!
     2. Set the session launcher’s default resource class for your project [How to select compute resources for your session](../../sessions/guides/select-compute-resources-for-session).
 
         :::info

docs/docs/10-users/60-sessions/guides/45-use-your-own-docker-image-for-renku-session.md → docs/docs/10-users/60-sessions/guides/00-environments/45-use-your-own-docker-image-for-renku-session.md

@@ -83,7 +83,7 @@ In the project page:
 
     :::tip
 
-    If the available resource classes are too small for your compute requirements, we can create a custom resource pool for you! See [Request a Custom Resource Pool](../resource-pools-and-classes#request-custom-resource-pool).
+    If the available resource classes are too small for your compute requirements, we can create a custom resource pool for you! See [Request a Custom Resource Pool](../../resource-pools-and-classes#request-custom-resource-pool).
 
     :::
 

docs/docs/10-users/60-sessions/guides/00-environments/_category_.yml

@@ -0,0 +1 @@
+label: Create Session Launcher Environments

docs/docs/10-users/60-sessions/guides/00-environments/index.md

@@ -0,0 +1,74 @@
+# Add a session launcher to your project
+
+A session launcher defines the environment and compute resources for a Renku session. The basic steps for creating a session launcher are:
+
+1. In the **Sessions** section of the project page, click on ➕ to add a new session launcher.
+2. Choose and configure an **environment** (see [Creating an environment for your session](#creating-an-environment-for-your-session) below).
+3. Select the **Resource class** that best fits your expected computational needs.
+
+    :::tip
+
+    Do you need more resources than are available in RenkuLab’s public resource classes? [Contact
+    us!](../../../community) We can configure a custom resource pool for your needs upon demand.
+
+    :::
+
+## Creating an environment for your session
+
+Renku supports a variety of ways of working with sessions. To determine what kind of Renku session
+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
+[2. Would you like packages to be pre-installed and ready to go when you (or anyone else) launches
+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 another language
+
+Working in some other language? That’s ok! You can run a wide variety of Docker images in Renku
+sessions! See [How to use your own docker image for a Renku
+session](use-your-own-docker-image-for-renku-session)
+
+### 2. Would you like packages to be pre-installed and ready to go when you (or anyone else) launches the session?
+
+#### → Yes please!
+
+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!
+
+→ If your code repository is **public**, see [How to create an environment with custom packages
+installed](create-environment-with-custom-packages-installed).
+
+→ If your code repository is **private**, see [How to create an environment with custom packages from
+a private code
+repository](create-environment-with-custom-packages-private-code-repository).
+
+#### → Having packages pre-installed is not so important to me right now.
+
+If you don’t need custom packages installed, you can get started quickly by simply selecting one or
+Renku’s pre-made **global environments**. When you create a session launcher, select **global
+environment** and choose one of the pre-made environments.
+
+When you launch a session with a global environment, you can still install packages on the fly.
+Please note, however, that these packages will not persist once you shut down your session. You will
+have to re-install them after you shut down and re-launch your session. In addition, the packages
+you install won’t be available for anyone else who launches a session from the launcher.
+
+If you’d like to permanently add the packages you need to your session environment, see [How to
+create an environment with custom packages
+installed](create-environment-with-custom-packages-installed).

docs/docs/10-users/60-sessions/guides/50-connect-to-renku-session-from-your-local-vscode.md

@@ -6,9 +6,9 @@ Would you prefer to work on your Renku project from the comfort of your local VS
 
 VSCode tunnels are supported in the following Renku session environments:
 
-- **Most Renku [global environments](add-session-launcher-to-project)** ≥ version `2.7.0`.
+- **Most Renku [global environments](environments/)** ≥ version `2.7.0`.
     - Global environments where VSCode tunneling is *not* supported include: the RStudio environment.
-- **All Renku [code based environments](create-environment-with-custom-packages-installed)** that were built (or rebuilt) after September 2, 2025  (release 2.7.0)
+- **All Renku [code based environments](environments/create-environment-with-custom-packages-installed)** that were built (or rebuilt) after September 2, 2025  (release 2.7.0)
 
 :::
 

docs/docs/10-users/60-sessions/guides/_80-create-dashboard.md

@@ -1,12 +1,12 @@
 # How to create a Dashboard (Streamlit, Plotly Dash)
 
-Renku allows Docker images with user-specific entry points. This feature makes it easy the creation of user-specific environments, including setting up Streamlit apps. Check [How to use your own docker image for a Renku session](/docs/users/sessions/guides/use-your-own-docker-image-for-renku-session)  for the full list of details and options.
+Renku allows Docker images with user-specific entry points. This feature makes it easy the creation of user-specific environments, including setting up Streamlit apps. Check [How to use your own docker image for a Renku session](/docs/users/sessions/guides/environments/use-your-own-docker-image-for-renku-session)  for the full list of details and options.
 
 There are mainly two options two have your own Streamlit app served in Renku, either without access to the codebase or with access to the code.
 
 # Create an app with a code-based environment
 
-Check [How to create an environment with custom packages installed](/docs/users/sessions/guides/create-environment-with-custom-packages-installed)  for the full list of details.
+Check [How to create an environment with custom packages installed](/docs/users/sessions/guides/environments/create-environment-with-custom-packages-installed)  for the full list of details.
 
 :::note
 
@@ -18,9 +18,9 @@ Your project might have a nice dashboard inside, which you would want others to
 
 To set up a dashboard with an environment built from your repository, you can follow these steps:
 
-1. Follow the steps for creating a [code-based environment](/docs/users/sessions/guides/create-environment-with-custom-packages-installed) above.
+1. Follow the steps for creating a [code-based environment](/docs/users/sessions/guides/environments/create-environment-with-custom-packages-installed) above.
 2. Once the image is done building, edit the environment and change it to a “Custom Environment”
-3. Edit the `Command` to be `["bash", "-c"]` and `Args` to correspond to your app - see common examples [here](/docs/users/sessions/guides/use-your-own-docker-image-for-renku-session).
+3. Edit the `Command` to be `["bash", "-c"]` and `Args` to correspond to your app - see common examples [here](/docs/users/sessions/guides/environments/use-your-own-docker-image-for-renku-session).
 
 Once you are done, your environment configuration should look something like this:
 
@@ -46,7 +46,7 @@ Create a session launcher using the **Custom Image** option, and provide the fol
 ["sh", "-c"]
 ```
 
-- Command Arguments CMD (fill in `<your-repo-name>/<your-app>`) ([learn more](/docs/users/sessions/guides/use-your-own-docker-image-for-renku-session)):
+- Command Arguments CMD (fill in `<your-repo-name>/<your-app>`) ([learn more](/docs/users/sessions/guides/environments/use-your-own-docker-image-for-renku-session)):
 
 ```json
 ["streamlit run $RENKU_WORKING_DIR/<your-repo-name>/<your-app>.py --server.port=8888 --server.address=0.0.0.0 --server.baseUrlPath=$RENKU_BASE_URL_PATH"]