Spring school 2026 (#140)

* update best practices python/r

* update data transfer manuals

* update running ollama manual

* include spring school page

* Apply suggestions from code review

Co-authored-by: Jelle Treep <40466121+jelletreep@users.noreply.github.com>

* revise workshop page

* update python environments

---------

Co-authored-by: Jelle Treep <40466121+jelletreep@users.noreply.github.com>
Co-authored-by: Jelle Treep <h.j.treep@uu.nl>

Author: ShaivanBhagat

docs/manuals/hpc-spring-school-2026.qmd

@@ -0,0 +1,139 @@
+---
+title: "HPC Spring School June 2026: SURF Research Cloud Workshop"
+---
+
+## Overview
+
+Welcome to the SURF Research Cloud workshop for the UU HPC Spring School 2026!
+
+During this hands-on workshop, you'll learn how to work effectively with SURF Research Cloud. There are several tutorials available for you to explore:
+
+| Topic | Section | Estimated time |
+| --- | --- | --- |
+| **Working with R/Python environments** | [Go to section](#working-with-r-python-environments) | 15-45 minutes |
+| **Data transfer methods** | [Go to section](#data-transfer-methods) | 15-45 minutes |
+| **Working with Ollama** | [Go to section](#working-with-ollama) | 20-40 minutes |
+| **Running long jobs** | [Go to section](#running-long-jobs-via-the-command-line) | 10-30 minutes |
+| **VS Code Remote-SSH** | [Go to section](#connecting-vs-code-to-research-cloud) | 30 minutes |
+
+Each tutorial includes step-by-step instructions. You can choose the ones most relevant to your research needs or interests. While there are several workspaces available that you can use to follow the tutorials, we recommend using the [VRE Lab](../workspaces/programming/vre-lab.qmd) workspace for most of them, as it comes with many relevant tools pre-installed.
+
+## Prerequisites
+
+**Required**
+
+Before starting the tutorials, you need:
+
+1. **SURF Research Cloud account**: You can login here [**Research Cloud portal**](https://portal.live.surfresearchcloud.nl/)
+2. **Active workspace**: You will need to create a workspace, depending on the tutorial you wish to follow. See [How to Create a Workspace](../first-steps.qmd#create-a-workspace) for guidance.
+
+**Recommended**
+
+Familiarity with the command line (terminal), git, GitHub and basic knowledge of Python/R will be helpful for some tutorials.
+
+## Workshop Tutorials
+
+### 1. Working with R/Python Environments {#working-with-r-python-environments}
+
+Learn how to create, manage, and use Python and R environments in your workspace. Working with environments is good practice for creating robust and reproducible projects, and makes it easier to install the exact same package versions that you are using currentlyon SURF Research Cloud.
+
+**What you'll learn:**
+
+- Creating virtual environments and managing packages
+- Creating requirements files for Python and R
+- Installing packages on SURF Research Cloud using `uv`, `conda`, and `renv`
+
+**Tutorials:**
+
+- [Working with Python Environments and Best Practices](../manuals/python-environment.qmd)
+- [Working with R Environments and Best Practices](../manuals/r-environment.qmd) 
+
+We recommend using the [VRE Lab](../workspaces/programming/vre-lab.qmd) workspace to follow these tutorial. Select `Python tools` (for working with Python Environments) and/or `RStudioUU` (for working with R Environments) under optional components in the last step of creating your workspace.
+
+**Estimated time:** 15-45 minutes (depending on any previous experience with environment management tools)
+
+---
+
+### 2. Data Transfer Methods {#data-transfer-methods}
+
+Transfer data to your Research Cloud workspace from your local computer, cloud storage, Yoda and/or GitHub. Learn which method works best for your data source and file sizes.
+
+**What you'll learn:**
+
+- Transferring files from your PC/laptop
+- Configuring connections to cloud storage such as Surfdrive, Researchdrive and/or Yoda
+- Choosing the right transfer method for your needs
+
+**Tutorials:**
+
+To find the best method to transfer your data, check out this [Interactive Data Transfer Tool.](../manuals/data-transfer-options.qmd) It will help you determine the best method based on your data source, workspace, and file sizes.
+
+You can explore the following tutorials for specific transfer methods:
+
+- [Data Transfer to and from Yoda using iBridges](../manuals/ibridges.qmd)
+- [Data Transfer to and from Yoda using iCommands](../manuals/icommands.qmd)
+- [Data Transfer from your computer using scp and rsync](../manuals/ssh-data-transfer-methods.qmd)
+- [Data Transfer between Research Cloud and Online Storage (Surfdrive, Researchdrive) using Rclone](../manuals/rclone-researchcloud.qmd)
+- [Data Transfer from GitHub/GitLab using Git](../manuals/git-clone.qmd)
+
+**Estimated time:** 15-45 minutes (depending on tutorial selected)
+
+---
+
+### 3. Working with Ollama {#working-with-ollama}
+
+Set up and use [Ollama](https://ollama.com/) directly in your Jupyter notebooks, e.g. for data extraction from documents or image analysis.
+
+**What you'll learn:**
+
+- Installing and configuring Ollama
+- Downloading models
+- Data extraction and Image description in Jupyter notebooks
+
+**Relevant Workspaces:** [VRE Lab](../workspaces/programming/vre-lab.qmd) with `Python tools` as optional component, [Python Workbench Desktop](../workspaces/programming/python-workbench.qmd)
+
+**Tutorial:** [Setting up and Using Ollama](../manuals/ollama.qmd) 
+
+**Estimated time:** 20-40 minutes
+
+---
+
+### 4. Running Long Jobs via the Command Line {#running-long-jobs-via-the-command-line}
+
+Keep computational tasks running even after (accidentally) closing your terminal or SSH connection. Essential for long-running analyses and simulations. It is also possible to automate pausing of the workspace to save costs.
+
+**What you'll learn:**
+
+- Running jobs in the background
+- Checking job status and output
+- Automating workspace pausing
+
+**Tutorial:**
+
+- [Running Long Jobs](../manuals/long-jobs.qmd)
+This tutorial is relevant if you have an analysis script or simulation that takes a long time to execute. 
+
+**Estimated time:** 10-30 minutes
+
+---
+
+### 5. Connecting VS Code to Research Cloud {#connecting-vs-code-to-research-cloud}
+
+Connect Visual Studio Code on your PC to your SURF Research Cloud workspace. This is useful e.g. if you want to use the VS Code extensions that you have installed.
+
+**What you'll learn:**
+
+- Setting up VS Code Remote-SSH extension
+- Connecting to your workspace
+- Editing files remotely
+- Using VS Code extensions on the remote workspace
+
+Works on any workspace with SSH access, however [VRE Lab](../workspaces/programming/vre-lab.qmd) is recommended. 
+
+**Tutorial:**
+
+- [VS Code Remote-SSH](../manuals/vscode-to-researchcloud.qmd)
+
+**Estimated time:** 30 minutes
+
+---

docs/manuals/ibridges.qmd

@@ -2,7 +2,7 @@
 title: Using iBridges on SURF Research Cloud
 ---
 
-The instructions below describe the how to setup iBridges to transfer data between SURF Research Cloud and Yoda or any other iRODS instance. It is possible to use iBridges in three different ways:
+The instructions below describe how to setup iBridges to transfer data between SURF Research Cloud and Yoda or any other iRODS instance. It is possible to use iBridges in three different ways:
 
 - as a python package 
 - via the command line interface (CLI)
@@ -18,14 +18,42 @@ The python package and the command line interface are available (or can be made
 
 ### Prerequisites
 
-Access to Yoda or another iRODS instance which hosts your data.
+Access to [Yoda](https://www.uu.nl/en/research/yoda) or another iRODS instance which hosts your data.
 
-iBridges needs to be installed on your workspace. Many SURF ResearchCloud workspaces developed by Utrecht University (such as Python and R workbenches) have iBridges preinstalled. 
+iBridges needs to be installed on your workspace. Most workspaces developed by Utrecht University (such as [Python](../workspaces/programming/python-workbench.qmd) and [R](../workspaces/programming/r-workbench.qmd) workbenches, [VRE Lab](../workspaces/programming/vre-lab.qmd)) have iBridges preinstalled. On workspaces developed by SURF, ibridges may need to be installed by the user. 
 
 - If you are working on a Desktop workspace, you can check by logging in to your workspace, clicking 'applications' in the top left corner, and clicking 'Development'. 
 - On non-desktop workspaces check if iBridges is installed by typing: `ibridges` in the terminal. If iBridges is installed, this should show you the program's help menu. On Jupyter or Rstudio workspaces, you need to open a terminal first: In Jupyter, click the + button in the file browser and select the terminal in the new Launcher tab ([find a short video here](https://jupyterlab.readthedocs.io/en/stable/user/terminal.html)).
 In Rstudio, In the bottom left panel, click the ‘terminal’ tab.
 
+
+#### What shall I do if iBridges is not on my workspace?
+
+If your workspace has python installed, you can install the packages using the command line (or aka terminal):
+
+::: {.panel-tabset}
+
+## GUI
+```bash
+pip install ibridgesgui
+```
+
+To start the GUI application you would then need to open a terminal and type in `ibridges gui` (Note: this will only work on Desktop workspaces).
+
+If you run into problems with running ibridgesgui, try running `sudo apt install libxcb-cursor0` in the terminal and then running `ibridges gui` again. Please contact us if you need help with installing iBridges or if you want to have iBridges preinstalled on your workspace.
+
+## CLI/API
+```bash
+uv tool install ibridges
+# OR
+pipx install ibridges
+```
+ibridges will then be installed. However it is possible that you may need to run `pipx ensurepath` to make it available on your path and restart your terminal before you can use the `ibridges` command. 
+
+Please contact us if you need help with installing iBridges or if you want to have iBridges preinstalled on your workspace.
+:::
+
+
 ### Configure iBridges
 
 To connect to a Yoda or any other iRODS instance you will need a so-called `irods_environment.json` which needs to be stored in a specific location. You can create this file by hand or use the iBridges GUI or CLI to create it for you.
@@ -40,37 +68,25 @@ To connect to a Yoda or any other iRODS instance you will need a so-called `irod
 
 If there are no templates in the drop-down menu of the configuration window, you will need to install the plugin. To this end you will need python and git and execute in power shell, git bash or Anaconda terminal:
 
-```
+``` bash
 pip install ibridges-servers-uu
 ```
 
 #### Configuration through the CLI
 
 If you want to connect to a server hosted by Utrecht University please check whether this information is already present for ibridges.
 
-```
+``` bash
 ibridges setup --list
 ```
 
 From that list simply choose the server you want to connect to with `ibridges setup uu-<server>` and follow the instructions.
 In case you get the message `No server information was found.` please install:
 
-```
+``` bash
 pip install bridges-servers-uu
 ```
 
-#### What shall I do if iBridges is not on my workspace?
-
-If your workspace has python installed, you can install the packages using the command line (or aka terminal):
-
-- GUI: `pip install ibridgesgui`
-- CLI/API: `pip install ibridges`
-
-To start the GUI application you would then need to open a terminal and type in `ibridges-gui`. (Note: this will only work on Desktop workspaces).
-
-Please contact us if you need help with installing iBridges or if you want to have iBridges preinstalled on your workspace.
-
-
 #### How to connect to a Yoda or iRODS instance not provided by Utrecht University?
 
 In this case you will have to create your irods_environment.json by hand:
@@ -97,7 +113,7 @@ More elaborate instructions can be found in the [iBridges GUI documentation](htt
 
 Simply try `ibridges --help` or `ibridges <command> --help` to get examples and help for the usage.
 
-For instructions on how to use the `ibridges` command please see the [iBridges documentation](https://ibridges.readthedocs.io/en/stable/cli.html).
+For instructions on how to use the `ibridges` command please see the [iBridges CLI documentation](https://ibridges.readthedocs.io/en/stable/cli.html).
 
 #### Using the python package
 

docs/manuals/icommands.qmd

@@ -2,18 +2,25 @@
 title: "Installing and using iCommands on Surf Research Cloud"
 ---
 
-The instructions below describe the process of data transfer between Surf Research Cloud and Yoda using iCommands. This manual is developed for workspaces based on a Linux operating system (including the Jupyter Notebook and RStudio workspaces). Transfer is also possible via the Webdav protocol using [Rclone](https://rclone.org). For large files iCommands is faster due to parallel transfer options.
+The instructions below describe the process of data transfer between Surf Research Cloud and [Yoda](https://www.uu.nl/en/research/yoda) using iCommands. This manual is developed for workspaces based on a Linux operating system (such as Ubuntu and Python Workspaces as well as Jupyter Notebook and RStudio workspaces). Transfer is also possible via the Webdav protocol using [Rclone](https://rclone.org). However, for large files iCommands is faster due to parallel transfer options.
 
 ### Prerequisites
 You will need some basic linux skills to be able to use the iCommands successfully. 
 If you don't have these skills, take some time to practice using sections 1, 2, 3 and 7 of this short [online course](https://swcarpentry.github.io/shell-novice) before proceeding. You can practice in the terminal (see step 1).
 
+You will also need access to [Yoda](https://www.uu.nl/en/research/yoda).
+
 ### Step 1: Make sure you are in a terminal
-- In Jupyterhub (Jupyter Workspace in Research cloud): 
+- In Jupyterhub ([Jupyter Notebook](../workspaces/programming/jupyter.qmd) or [VRE Lab](../workspaces/programming/vre-lab.qmd) in Research cloud): 
   To open a new terminal, click the + button in the file browser and select the terminal in the new Launcher tab
   ([find a short video here](https://jupyterlab.readthedocs.io/en/stable/user/terminal.html)).
-- In Rstudio (Rstudio workspace in Research cloud):
+- In Rstudio ([Rstudio workspace](../workspaces/programming/rstudio.qmd) in Research cloud):
   In the bottom left panel, click the 'terminal' tab.
+- In [Python](../workspaces/programming/python-workbench.qmd) and [Ubuntu](../workspaces/plain/ubuntu.qmd) Desktop workspaces:
+  Open a terminal. You can find it under Applications.
+- In [Python](../workspaces/programming/python-workbench.qmd) and [Ubuntu](../workspaces/plain/ubuntu.qmd) CLI workspaces:
+  You are already in a terminal after logging in to the workspace. 
+
 
 ### Step 2: Install iRODS iCommands
 Some workspaces have iRODS iCommands preconfigured. This should be visible in step 1 when creating a workspace.
@@ -35,21 +42,27 @@ sudo apt-get install -y irods-icommands
 
 ### Step 4: Initialize connection to iRODS
 
-Initialize the connection to the Yoda system as follows:
+Navigate out of the `.irods` folder and to a folder where you want to move files from Yoda. Run `cd ~` to navigate to your home directory and then run the following command to initialize the connection to iRODS:
 
 ```
 iinit
 ```
 
-Type your Yoda password when requested.
+If you see `command not found: iinit` after running the command, it means that iCommands is not properly installed. Run `sudo apt-get install -y irods-icommands` to install iCommands and try again.
+
+After running `iinit`, you will be prompted to enter your Yoda password. You can find this as a [data access password](https://www.uu.nl/en/research/yoda/using-data-access-passwords). This is not the same as your Research Cloud or solis-id password.
 
 Type `ils` to see whether the connection has been established. The output of the `ils` command will list the current Yoda folder and the folders that are located within the current folder.
 
 `iinit` and `ils` are commands which can only be used when icommands is active. Some of these commands are very similar to standard unix commands. When icommands is active you can still operate the HPC system using normal unix commands. A complete list of all 'icommands' can be found [here](https://docs.irods.org/4.2.9/icommands/user/).
 
 ### Step 5: Transferring data
 
-Standard transfer of a single file can be done using `iget` and `iput`
+Standard transfer of a single file can be done using `iget` (to retrieve from Yoda to your workspace) and `iput` (to upload to Yoda from your workspace).
+```
+iget /uu/home/<Yoda-folder-name>/<file-name>
+iput <workspace-file-name> /uu/home/<Yoda-folder-name>/
+```
 
 The `irsync` command can be used to synchronize entire directories between Yoda and Cartesius. The command is used as follows.