Creating and disseminating educational resources for SSPCloud users

Startup guide

Authors

Lino Galiana

Olivier Meslin

This tutorial aims to be a practical guide for people developing educational resources in or Python and wishing to disseminate them easily through the SSPCloud.

To make this possible, a few technical prerequisites are needed - these are outlined in Important 1.

The aim of this tutorial is to get you started quickly on building educational resources with a state-of-the-art level of reproducibility. The next sections explain how to develop educational resources, and how to disseminate them on the SPPCloud. Keep in mind that this tutorial is intended for people developing resources, not for the users of these resources.

Important 1: Technical requirements to deploy educational resources
  • A minimum level of proficiency in Git is required to develop and make available online training resources. However, accessing to these resources on the SSPCloud does not require any familiarity with Git.
  • Quarto the automated report and website builder inherited from R Markdown.
  • An understanding of the fundamental difference between making resources available for execution on a local computer or on a server like SSPCloud. See SSPCloud documentation.
  • Some knowledge regarding deployment of resources using Github Actions is useful. This tutorial gives a few templates but understanding what is happening behind the stage is not in the scope of that tutorial.

1 Why share educational resources on SSPCloud?

Sharing educational resources on SSPCloud offers several advantages, particularly for educators and learners working with computational tools like R or Python. Here are the key benefits:

  1. Instant access via a simple link SSPCloud allows users to launch pre-configured workspaces through a simple HTTPS link. Doing so, there is no need for any local installation or complex setup: learners can start working immediately, directly in their browser.

  2. Standardized and reproducible environments Everyone accesses the same cloud-based environment, including all necessary packages, tools, and datasets. This ensures full consistency across learners, removing issues related to differing operating systems, versions, or missing dependencies.

  3. Scalable computing power SSPCloud offers access to robust computational resources that can scale with your needs. From beginner tutorials in Python or R to advanced workflows involving large datasets or machine learning models, the platform can support a wide range of educational use cases.

As outlined in the SSPCloud documentation, it’s important to understand that the platform separates code (Git), data (S3), and environment configuration. These components are dynamically combined when launching a compute session.

For training designers, this architecture ensures high reproducibility and fine-grained control over the environment. For users, it eliminates the need to install software, manage system permissions, or configure their local machine—making it easy to jump straight into the tutorial.

An illustration of the SSPCloud functioning

2 Which materials should be used for trainings?

When designing effective training materials, it’s essential to choose formats that actively engage learners and support comprehension. While PDFs, slide decks, and videos are all valuable for delivering content, this guide focuses on static websites and interactive environments, which are particularly well-suited for hands-on learning. These environments enable learners to apply concepts immediately, test code in real time, and actively engage with the material—leading to deeper understanding and better long-term retention.

In the sections that follow, we’ll begin by comparing various interactive environments based on the programming language they support. Then, we’ll walk through how to build and structure them using Quarto.

2.1 Which interactive environment should you use ?

Jupyter notebooks1 offer an interactive interface that allows you to write Python code, test it, and see the result below the instruction rather than in a separate console. Jupyter notebooks are essential in the fields of data science and education and research because they greatly simplify exploration and experimentation.

They allow you to combine text in Markdown format (a lighter markup text format than HTML or \(\LaTeX\)), Python code, and HTML code for visualizations and animations in a single document.

Initially, Jupyter was the only software offering these interactive features. Now, there are other ways to benefit from notebook advantages while having an IDE with more comprehensive features than Jupyter. For this reason, as of 2025, we recommend developing resources with VSCode , a general-purpose code editor but offering excellent features in Python, rather than with Jupyter. For more information on using notebooks in VSCode, refer to the official documentation.

Note

Although we recommend developing resources with Vscode rather than with Jupyter, final users will be able to open your educational resources with Jupyter if they want to.

Example with Jupyter

Example with VSCode

In , notebooks are not commonly used - even though they offer several features that are particularly valuable for educational purposes.

When designing -based training materials, two main options are available, each with its own pros and cons:

  1. Providing access to an HTML website
    • Advantages: Solutions to exercices can be hidden, interactive widgets can be used to offer hints or guide learners step by step, and the layout is optimized for reading.
    • Drawbacks: This is not an interactive environment—learners must open a separate RStudio session to try out the code, which can disrupt the flow of learning.
  2. Providing access to a Quarto Markdown (.qmd) file
    • Advantages: Fully interactive—learners can run code directly within the environment, benefiting from live feedback and hands-on practice.
    • Drawbacks: All answers and code are visible by default, which may reduce engagement and exploratory effort from the learners.

Since the first option can become cumbersome - especially when learners need to copy and paste large blocks of code - it is generally recommended to use the second option in most cases. Providing direct access to a Quarto Markdown file helps minimize the risk of hard-to-reproduce errors that often arise when learners switch between an HTML tutorial and their R session.

Exemple with RStudio
Why learnr Is Not Recommended

While learnr allows for the creation of interactive and advanced elements such as quizzes—making it well-suited for beginner tutorials—it has some important limitations.

First, it requires deployment on a Shiny server, which can be costly and complex to maintain. Additionally, in learnr, code cells do not share a global environment. This means variables and objects created in one chunk are not accessible in others, making it difficult to manage state or build on previous steps.

These restrictions limit the usefulness of learnr for more complex tutorials, where maintaining continuity and evolving context across the tutorial is essential.

2.2 Introducing Quarto to create training resources

Quarto is an open source program for creating Python and reproducible tutorials. It makes it possible to mix seamlessly code and text in the same document and can handle many output formats, including html, pdf or notebook (.ipynb extension). Quarto is strongly recommended for the development of educational resources.

This tutorial assumes that educational resources and training material will be made available in two forms:

  • Quarto websites, mixing text and code chunks;
  • Interactive environment (see ☝️).

3 A step-by-step tutorial

3.1 Step 1: create a Github repository from a template

3.1.1 What are templates and why use them?

The very first step towards developing educational resources consists in creating a Github repository that will contain them all. We recommend that you use the templates developed specifically for the AIML4OS project. There are two different templates, depending on the language you want to use. They are both hosted on Github :

These templates contain all what you need to produce resources that can be easily made available as websites or as interactive environments on the SSP Cloud. More precisely, these templates contain:

  • a minimal Quarto website with visual elements reflecting AIML4OS aesthetic;
  • a minimal example of a Quarto document producing a Jupyter Notebook ( only);
  • a minimal example of a Quarto document mixing Markdown text and R code ( only);
  • what is needed to manage dependencies (what packages are needed to run the codes, and in which version);
  • scripts for Github Actions workflow for automated deployment (don’t be afraid, see below!).
If you are not AIML4OS member and follow this guide anyway

You can still use the templates - just remove the style components using AIML4OS aesthetic.

3.1.2 How to use a template?

Here is what to do to re-use a template:

  • Go to the Github page of the chosen template;
  • Click on the “Use this template” button and then on “Create a new repository” (see Figure 1);
Figure 1: Use this template button on Github
  • Choose carefully the owner and the name of the new repository:
    • Owner: by default the owner is the creator of the fork, but it may be preferable to choose a Github organization (for instance the AIML4OS organization);
    • Name: give the repository a meaningful name, for instance “Intro_To_Deep_Learning” or “Intro_To_Linear_Regression”;
  • Set Choose visibility to Public.

3.2 Step 2: define your development configuration on the SSPCloud

SSPCloud is not only useful to disseminate educational resources; it is also the right place to develop them. Doing so will facilitate resource dissemination as the environment used for training will be equivalent to the one used for development. In other words, we strongly recommend that you develop on SSPCloud because this will help a lot to make your educational resources reproducible.

Some elements of this development environment will be re-used to provide a ready-to-use configuration for learners. However, learners don’t need to be familiar with the technical concepts of configuration: pre-configured environments do exist so that learners can concentrate on acquiring skills!

3.2.1 What is a configuration and why is it useful?

The best way to develop resources on the SSPCloud is to define your own development configuration. In technical terms, a configuration is just a service available on the SSPCloud (eg: RStudio or VSCode) with additional user-defined settings such as: the Github repository you want to work on, your Github credentials, the size of memory and number of CPU you want to use, the initialization script you want to run…

Defining a configuration has two advantages:

  • it lets you define explicitly the technical environment you want to use for a specific project;
  • you can resume working on your project at any time in only one click, and be sure that the technical environment remains exactly the same.

Your ready-to-use configurations are listed on the right-hand-side of the “My services” tab. To use a configuration, you just have to click on Launch (red rectangle). You can modify or delete an existing configuration by clicking on the contextual menu (green rectangle).

Note

Defining a configuration may seem complicated the first time you do it, but you will get used to it in no time.

3.2.2 How to define a configuration

Here is how to define a ready to use development configuration using the SSPCloud. A video version is proposed below the text.

  • Go the “My Services” Tab and click on “New Service”;
  • Choose Rstudio and click Launch;
  • Customize the configuration by changing four settings:
    • In the “Friendly Name” field, choose a meaningful name (for instance dev_Intro_To_Linear_Regression);
    • In the “Repository” field of the “Git” tab, paste the URL of the repository you created in step 1 (for instance: https://www.github.com/AIML4OS/Intro_To_Linear_Regression);
    • In the “Network Access” tab, enable access to your service through port 5000;
    • In the “Initialization scripts” tab, paste this URL https://raw.githubusercontent.com/{OWNER}/{REPO}/refs/heads/main/init.sh, after replacing OWNER and REPO by the owner and repository name you chose in step 1;
  • Click on Save configuration;
  • Click on Launch;
  • Open the Rstudio service;
  • Rename the Rproj file with a meaningful name (for instance Intro_To_Linear_Regression.Rproj);
  • Click on the Rproj file to open the RStudio project;
  • Run renv::restore() (this may take a while);
  • You’re all set!
  • Go the “My Services” Tab and click on “New Service”;
  • Choose Vscode-python and click Launch2;
  • Customize the configuration by changing four settings:
    • In the “Friendly Name” field, choose a meaningful name (for instance dev_Intro_To_Linear_Regression);
    • In the “Repository” field of the “Git” tab, paste the URL of the repository you created in step 1 (for instance: https://www.github.com/AIML4OS/Intro_To_Linear_Regression);
    • In the “Network Access” tab, enable access to your service through port 5000;
    • In the “Initialization scripts” tab, paste this URL https://raw.githubusercontent.com/{OWNER}/{REPO}/refs/heads/main/init.sh, after replacing OWNER and REPO by the owner and repository name you chose in step 1;
  • Click on Save configuration;
  • Click on Launch;
  • Open the Vscode service;
  • You’re all set!
Video version

Here’s a video summarizing these manual gestures for configuring the Python environment. Setting up the R environment is very similar. The values entered in the fields, in particular the initialization script, are those given in the example above: adapt these values to your needs.

3.2.3 How to use an existing configuration

Once a configuration is defined, using it is very easy and very fast:

  • Go the “My Services” Tab;
  • On the right side of the screen, find the configuration of your project and click on Launch;
  • Open the Rstudio service;
  • Click on the Rproj file to open the RStudio project;
  • Run renv::restore() (this may take a while);
  • You’re all set!
  • Go the “My Services” Tab;
  • On the right side of the screen, find the configuration of your project and click on Launch;
  • Open the VSCode service;
  • You’re all set!

3.3 Step 3: develop resources with Quarto

If you have created a repository from a template and defined a development configuration, developing resources basically means modifying and extending the minimal examples available in your repository.

Git, git, git, git, git

It is absolutely essential that you commit and push your changes on a regular basis (every 30 minutes or so), because your service (Rstudio or VScode) is not persistent, meaning that any changes that were pushed before closing the service are permanently lost.

3.3.1 Change the URLs

The first thing you must do is changing the URLs of the repository in the _quarto.yml file:

  • Open the _quarto.yml;
  • in the site-url and repo-url fields, replace the URL of the template by the URL of your repository. In step 1, you chose the Owner and the Name of your repository, so the URL should be https://github.com/{Owner}/{Name};
  • Commit this change.

3.3.2 Manage data (if needed)

Depending on your project, your scripts may require some data, for instance to train a model. However, when you start a service on SSP Cloud (VSCode or Rstudio), it does not contain any data. That implies that you have to download data into your service. Of course, you could do it by hand every time you start a service, but we strongly recommend that you automatize this step. The simplest way to proceed is to upload your data on the S3 storage service of SSPCloud, and then download it from S3 into your service every time you start a service.

3.3.2.1 Upload data to S3

The simplest way to upload data to S3 is to use the graphical interface available on SSPCloud. You have to do only once (except if you want to change or update the data, of course). To to so, click on “File Explorer” on the left hand and then on “My data”.

You can upload a file by navigating clicking on “Upload file” (blue rectangle). You can also create a subfolder by clicking on “Create directory” (red rectangle).

Three remarks to keep in mind
  • Choose carefully in which subfolder you upload your files, because moving files from one subfolder to another one on S3 is not very convenient.
  • Remember that only open data can be uploaded on S3.
  • By default, only you can see the files upload in your bucket. If you want other people to access the data, do not forget to make publicly available by clicking on the eye on the right hand side (green rectangle).

Once again: no sensitive data!!

3.3.2.2 Download data

To download data automatically into your service, you just have to adapt the download_data.sh file (in the sspcloud folder). There are two things you can change:

  • DEST_DIR is the folder in your service where data will be downloaded (/home/data/ by default);
  • DATA_PATH is the S3 path to your data (where it is downloaded from).

To obtain the S3 path to your data, use the File Explorer to navigate and find the file you want. The S3 path of your file is simply the path of the folder available in the top right corner of the explorer (red rectangle) and the name of the file (blue rectangle). In the screenshot below, the path of the first file is then: s3/oliviermeslin/data_SILC_PUF/data_SILC_d2013.parquet.

3.3.3 How to write Quarto documents?

Most of the resources you will develop will take the form of Quarto documents, that you will either provide to final users or compile to final outputs (for instance, websites or Jupyter notebooks). As a consequence, you must learn how to use Quarto. Fortunately, Quarto is easy to use, has an amazing documentation and there are plenty of resources online to help you.

To to get started with Quarto documents, there are three basic elements you should know about: the header, raw text with Markdown formatting, and code chunks. We strongly recommend that you refer to the official Quarto documentation and in particular to the beginner Quarto tutorial.

3.3.3.1 The header

Your Quarto document typically starts with a YAML header to define metadata such as author, title, and so on. Here is a simple example. You can also have a look at the headers of the Quarto files available in the templates. One particular important setting is the format setting: it tells what output should be produced (html, notebook…) when compiling Quarto compiles the document.

---
title: "My beautiful Quarto Report"
author: "Mickey mouse"
---

3.3.3.2 Raw text with Markdown formatting

A Quarto document contains blocks of text with Markdown formatting. See here for a detailed presentation of Markdown. Here is a short example:

This is text with *italics* and **bold**.

We can define lists and sublists :

- first element;
- second element;
    - first sub-element;
    - second sub-element.

This code will result in the following formatted text:

This is text with italics and bold.

We can define lists and sublists:

  • first element;
  • second element;
    • first sub-element;
    • second sub-element.

3.3.3.3 Code chunks

A Quarto document can also contain blocks of code inside code chunks, denoted with triple backticks and the language you use. Adding a name to each chunk is a good practice (nice_code in the example below). You can use chunk options to change the behavior of the chunk (for instance if you want to show some code without executing it).

```{r}
#| label: nice_code
# Load packages
library(ggplot2)

# Plot mpg vs hp
ggplot(mtcars, aes(x = hp, y = mpg)) +
  geom_point() +
  theme_minimal()
```
```{python}
#| label: nice_code
import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

3.3.4 Developing resources

Developing resources (html pages published on the website or interactive environments) with the AIML4OS templates is very easy: you just have to write text and code chunks in the existing qmd files (index.qmd and chapter1.qmd) or to add new Quarto documents. Two important remarks:

  • The index.qmd file is the starting page of your project: you should not delete or rename it.

  • You must specify the output format you want in the header of each qmd file:

    • if you want a static html page, specify format: html;
    • if you want a Jupyter notebook (Python only), specify format: ipynb;
    • if you want a Quarto file with R chunks (R only), do not specify anything.

3.3.4.1 Developing and previewing a website

The first kind of output you may want to produce is a static website, consisting in a series of html documents. If you add new pages to the website (preferably in the chapters subdirectory), do not forget to add them to the structure of the website by modifying the _quarto.yml file in two places: in the render argument (so that Quarto compiles them), and in the contents of the sidebar argument (so that all chapters are in the sidebar of the website).

It is often convenient to have a look at what this website looks like while developing it. You can preview your website from command line by executing:

quarto preview --port 5000 --host 0.0.0.0

Then go to https://datalab.sspcloud.fr/my-services, open the README of the service you are using and click on the link to the external port.

Figure 2: Accessing website preview
What to do if you can’t access the website preview?

If you can’t access the website preview because there is no link in the README, it is likely that you forgot to open port 5000 in your configuration. This is easily solved:

  • Close your RStudio/VSCode service (after committing and pushing all changes!);
  • Modify your configuration: in the “Network Access” tab, enable access to your service through port 5000 and save this new configuration;
  • Launch again your RStudio/VSCode service.

3.3.4.2 Developing interactive scripts

The second kind of output you may want to produce are interactive environments. These are particularly useful if your resources contain exercises. The final outputs will be quite different for R and Python (Jupyter notebooks for Python, Quarto documents with R chunks for R), but these resources can nonetheless be developed using Quarto.

Here is how you can produce a Quarto file with R chunks:

  • Create a new Quarto file and store it in the notebooks subfolder;
  • Develop the content;
  • Do NOT add the qmd file to the list in the render argument of the _quarto.yml file. This file does not need compilation.

The notebooks subfolder of the R template already contains an example.

Warning

You should not use install.packages() anywhere in your R resources because it is not the proper way to manage package requirements (see below for recommendations on dependency management).

Here is how you can produce a Jupyter notebook for Python:

  • Create a new Quarto file and store it in the notebooks subfolder;
  • Do not forget to write format: ipynb in the header;
  • Develop the content;
  • Add the qmd file to the list in the render argument of the _quarto.yml file, so that Quarto compiles it into a Jupyter notebook.

The notebooks subfolder of the Python template already contains an example (notebook1.qmd).

Warning

You should use pip install anywhere in your notebooks because it is not the proper way to manage package requirements (see below for recommendations on dependency management).

3.3.5 Managing dependencies when developing resources

A major challenge in any data science project is to make sure that its codes can be re-run without error by someone working in a different environment (this is called portability). Various technical requirements must be met to ensure portability; one of them is to keep track of all packages needed to run the code (and of the exact version of each package!), so that a new user can reinstall them easily. This section explains how to manage these dependencies using the right tools.

The dependency management tool depends on the language you use:

  • If you use R, we recommend that you use renv;
  • If you use Python, we recommend that you use uv.

renv is an R package that helps you manage the dependencies of each of your projects. It means that renv lets you keep track of what packages are needed to run your code, and in what exact version. More precisely, using renv adds two specific files to your project:

  • The lockfile renv.lock records information about every package used in the project, so that these packages can be re-installed on a new machine;
  • the .Rprofile project file. This file is run automatically every time you start R so that renv is used properly.

Here is how to use renv:

  • The first step in using renv is to initiate the tracking of dependencies using renv::init(). You do not need to do it if you use the R template because this was already done in the template.
  • When developing resources, you should regularly run renv::snapshot(). This command will analyze your R and Quarto scripts, detects what packages are used, and updates the renv.lock file. Do not forget to commit and push the changes to the renv.lock file!
  • When you start working on your project with a new service, you should run renv::restore(). This command will reinstall all the packages listed in the renv.lock file.
Warning

If you forget to update the renv.lock file, your Github Actions workflow is likely to fail, and you probably won’t be able to execute your R script in a new RStudio service. Keep calm, here is the solution: just run renv::snapshot(), commit and push the changes to the renv.lock file. This should solve the problem.

For more information, see the official documentation of renv.

uv is a fast Python package manager that helps you track and manage dependencies per project, similarly to renv for R. More precisely, uv can be used to create a virtual environment for your Python project. A virtual environment contains your project’s Python and its packages, and is isolated from other projects and the system’s Python. This means that different projects can use different versions of packages (and even different versions of Python!) without conflicts. uv helps create and manage these virtual environments easily, making sure all needed packages for your project are installed and kept organized. Using uv, you can ensure your project is reproducible, fast to install, and easy to deploy.

Here is the very short introduction on how to use uv:

  • The basic command to start using uv is uv init. This command adds to your project the pyproject.toml file that defines the project dependencies and metadata. This file is the central piece of the dependency management. You do not need to use this command if you use the Python template because this has already been done (the template already contains a pyproject.toml file).

  • When you start using a new package in your project, you must explicitly add it to the dependencies by running the command uv add [package_name]. This command will add this package to the pyproject.toml file.

  • Commit and push the changes in the pyproject.toml file.

  • When you want to recreate your environment from scratch on a new machine (or in a new service), you must run the command uv sync. This command will install all packages specified in the pyproject.toml file (and their own dependencies). You do not need to use this command if you use use the Python template because the initialization script already runs uv sync.

Warning

If you forget to use uv add [package_name] to add to your pyproject.toml file, your Github Actions workflow is likely to fail, and you probably won’t be able to execute your Python script in a new VSCode service. Keep calm, here is the solution: just identify what are the missing packages, use git add, commit and push the changes to the pyproject.toml file. This should solve the problem.

3.4 Step 4: set up a Github pages website

This step is optional, depending on whether your resources include a website. You can skip this step if your resources consist only in interactive environments (Jupyter notebooks for Python, interactive Quarto documents with R chunks for R).

3.4.1 What are Github Actions and Github pages and why are they useful?

If you are developing a website or Jupyter Notebooks for educational purposes, you probably want to publish them online. If you perform the publication manually (building the website/notebooks, then publishing them), you’ll have to re-do this series of tasks every time you change your website. This is time-consuming, repetitive and boring. But fortunately, you can automate this process thanks to GitHub Actions and Github Pages:

  • GitHub Actions is a tool built into GitHub that runs pre-defined tasks like testing, building, and deploying code when specific events occur in a repository. For instance, GitHub Actions may perform a series of task every time you push on the main branch of your repository, without you doing anything manually.
  • GitHub Pages is a another tool from Github that lets you publish static websites directly from a GitHub repository; it is often used for project documentation or personal portfolios.

The main message is: by combining GitHub Actions with GitHub Pages, you can set things up so that every time you make changes to your repository, GitHub Actions automatically updates your website and publishes it on GitHub Pages. This will save you a lot of time!

3.4.2 Create the gh-pages branch

When developing resources, you will most likely use the main branch. However, for Github Actions to work, you need an additional branch gh-pages used by Github to deploy websites. This one will be rewritten automatically by Github after every Github Actions workflow. However, you need to create it first. This should be done only once. Quarto documentation gives this command to create that branch. Be careful with that command, do not use before having done a first push on Github.


git checkout --orphan gh-pages # Create an empty branch called gh-pages 
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages # Pushing so that the gh-pages branch exists on the remote repo
git checkout main

3.4.3 Define a Github Actions workflow

You need to define a Github Actions workflow to automate output construction and deployment. A GHA workflow is a list of instructions (for instance: install R, install packages…) that are executed automatically every time a certain event happens (for instance every time you push on the main branch). A GHA workflow is defined using specific yaml scripts, located in the .github/workflows directory of your repository. The templates already contain standard workflows that you can use as a starting point. We recommend that you have a careful look at these workflows; comments were added so that they are easy to follow.

A few important remarks on automated deployment:

  • The website is deployed at an URL that depends on the owner and the name of the repository: https://{REPO_OWNER}.github.io/{REPO_NAME}/.
  • You can monitor Github Actions jobs in the “Actions” tab of the Github repository of your project. Do not be afraid if your jobs fail at first; getting Github Actions to work often requires some debugging.

3.4.4 Add the website URL to your Github repository

You can add the website URL to your Github repository so that it is easier to find. To do so, go to your repository using your browser, click on the little wheel on the far right (see the screenshot below), paste your website URL in the Website field, and save changes.

3.5 Step 5: make your interactive environments easily available on the SSP Cloud

This step is optional, depending on whether your resources include interactive environments (Jupyter notebooks for Python, interactive Quarto documents with R chunks for R). You can skip this step if your resources consist only in a Quarto website.

Python only: accessing the Jupyter Notebooks

Notebooks are automatically made available through the website deployed via Github Actions. Their location on the website depends on the location of of the qmd used to build them within the Git repository. For example, the notebook available in the Python template will be accessible via this link because the qmd file notebook1.qmd is located in the AIML4OS-template-quarto-python/notebooks/ folder of the repository.

R only: accessing the Quarto files

Quarto exercise files with R chunks can be used directly, no compilation is necessary. As a consequence, they are located on the Github repository, not on the website. To use these files, you must use the raw Github URL. This URL is available by clicking on the raw button when opening the file on Github. For example, the exercise available in the R template will be accessible via this link because the qmd file exercise1.qmd is located in the AIML4OS-template-quarto-r/exercises folder of the repository.

3.5.1 The initialization script for trainees

Up to now, we have explained how to initialize and pre-configure the trainers’ development environment (with the init.sh script). It is important to understand that while this pre-configuration is convenient but not essential when building educational resources, defining such a pre-configured environment is mandatory when making ready-to-use tutorials available to trainees. For this purpose, the templates offer an example to be edited, depending on the URL on which your resources are made available.

The script init-trainees.sh provided in the sspcloud folder of the template helps you to configure the environment for trainees on the SSPCloud. This script does two things: 1/ install the environment needed to run the notebook; this is greatly facilitated by the use of uv; 2/ download the notebook you want to provide trainees with. You do not need to modify this script. This script takes only one argument: the path of the notebook within the website (see next section). If the notebook you want to make available is located at is available at https://aiml4os.github.io/AIML4OS-template-quarto-python/notebooks/notebook1.ipynb, then this argument should be notebooks/notebook1.ipynb.

How to use the initialization script

Previous sections demonstrated how to personnalize the initialization script. Here is an important remark on how to use it: you must put the raw github URL of the script in the Initialization scripts field of the configuration. This URL is available by clicking on the raw button when opening the file on Github (see screenshot below). The URL should have a pattern similar to this one: https://raw.githubusercontent.com/InseeFrLab/AIML4OS-template-quarto-python/refs/heads/main/sspcloud/init-trainees.sh.

3.5.2 Create an auto launch URL

A convenient feature of SSPCloud is that you can make a whole training environment available through one URL link: in one click, trainees open a VSCode service that contains a Jupyter notebook, the data used by the notebook, all dependencies needed to run the notebook, and sufficient resources to run the code.

To do so, just follow two steps:

  • Define all aspects of the training environment using the usual interface. Here are the elements you will probably want to configure:

    • Friendly Name: do not forget to use a meaningful name (“Intro_To_Deep_Learning”), that will be more convenient for trainees;

    • Resources: choose the requests and limits that are well-suited for your use case. Some trial-and-error might be necessary here. However, in most cases, you don’t need to change the resources there because default SSPCloud settings fit most needs.

    • Initialization scripts:

      • Use a custom script (URL): paste the URL to the initialization script for trainees (see previous section).
      • Arguments for the custom script: write the name of the notebook (see previous section).

    • GIT: In the “Repository” field, paste the URL of the Github repository containing the resources.

  • Copy the link provided at the top of the interface by clicking on “Copy Auto Launch URL”, and paste it wherever you want. Anyone with an SSPCloud account can use it to open a pre-configured service. Do not forget to test your link a few times to be sure it works. Do not be afraid if it does not work on the first time, some trial-and-error is often necessary.

Note

An auto-launch URL is typically very long, something like: https://datalab.sspcloud.fr/launcher/ide/vscode-python?name=Notebook1&version=2.3.18&s3=region-79669f20&init.personalInit=«https%3A%2F%2Fraw.githubusercontent.com%2FAIML4OS%2FAIML4OS-template-quarto-python%2Frefs%2Fheads%2Fmain%2Fsspcloud%2Finit-trainees.sh»&init.personalInitArgs=«notebooks%2Fnotebook1.ipynb»&git.repository=«https%3A%2F%2Fgithub.com%2FAIML4OS%2FAIML4OS-template-quarto-python.git»&autoLaunch=true

We recommend two things:

  • Read carefully the auto-launch URL a few times (don’t be afraid!). You will see that it simply contains all the elements you defined in the configuration: the service you want to use (VSCode/RStudio), the friendly name, the URL of the init script and so on. This is not so complicated!
  • Check that there is no sensitive information in the Autolaunch URL (such as your Github token). If something looks strange, take the time to understand what is the problem.

3.5.3 Create a launch button for your website (bonus)

Let’s say you have done everything described before, and you have a working auto-launch URL. You could of course send it to trainees and ask them to copy and paste it in their browser to access the service, but a ready-to-use button is much more user-friendly! Just take this code snippet as a basis and replace AUTOLAUNCH_URL_THERE with your own quick launch URL:

<a href="AUTOLAUNCH_URL_THERE" target="_blank" rel="noopener" data-original-href="AUTOLAUNCH_URL_THERE"><img src="https://custom-icon-badges.demolab.com/badge/SSP%20Cloud-Launch_with_RStudio-blue?logo=vsc&amp;logoColor=white" alt="Onyxia"></a>

which, when formatted, will give a button like this

Onyxia 
<a href="AUTOLAUNCH_URL_THERE" target="_blank" rel="noopener" data-original-href="AUTOLAUNCH_URL_THERE"><img src="https://custom-icon-badges.demolab.com/badge/SSP%20Cloud-Launch_with_VSCode-blue?logo=vsc&amp;logoColor=white" alt="Onyxia"></a>

which, when formatted, will give a button like this

Onyxia

3.5.4 Add your resources on the training webpage hosted on the SSP Cloud

to be completed

Footnotes

  1. Jupyter originated from the IPython project, an interactive environment for Python developed by Fernando Pérez in 2001. In 2014, the project evolved to support other programming languages in addition to Python, leading to the creation of the Jupyter project. The name “Jupyter” is an acronym referring to the three main languages it supports: Julia, Python, and R.↩︎

  2. By default, this service includes a Python installation, but does not offer additional software such as R. For multi-language training, you can use the Vscode-r-python-julia service.↩︎