diff --git a/docs/images/workshops/manager_1.png b/docs/images/workshops/manager_1.png new file mode 100644 index 0000000000000000000000000000000000000000..2a7d42ce336142d00b68025ecae8940f05ef0945 Binary files /dev/null and b/docs/images/workshops/manager_1.png differ diff --git a/docs/images/workshops/manager_2.png b/docs/images/workshops/manager_2.png new file mode 100644 index 0000000000000000000000000000000000000000..adeed8aec6b62301d357e33c9edcb7a23058a0c3 Binary files /dev/null and b/docs/images/workshops/manager_2.png differ diff --git a/docs/images/workshops/manager_3.png b/docs/images/workshops/manager_3.png new file mode 100644 index 0000000000000000000000000000000000000000..c3044a6fb2c716384b579820b59eefbeab2d4b5d Binary files /dev/null and b/docs/images/workshops/manager_3.png differ diff --git a/docs/images/workshops/manager_4.png b/docs/images/workshops/manager_4.png new file mode 100644 index 0000000000000000000000000000000000000000..80cc238421ad6ab84e7956314987336908fd4fa8 Binary files /dev/null and b/docs/images/workshops/manager_4.png differ diff --git a/docs/images/workshops/manager_5.png b/docs/images/workshops/manager_5.png new file mode 100644 index 0000000000000000000000000000000000000000..75dd2750b9e813861da02b236a79cc802575cc18 Binary files /dev/null and b/docs/images/workshops/manager_5.png differ diff --git a/docs/images/workshops/workshop_1.png b/docs/images/workshops/workshop_1.png new file mode 100644 index 0000000000000000000000000000000000000000..8d76a3ad515443ac1d4c336fa49a09c17ebd2b56 Binary files /dev/null and b/docs/images/workshops/workshop_1.png differ diff --git a/docs/images/workshops/workshop_2.png b/docs/images/workshops/workshop_2.png new file mode 100644 index 0000000000000000000000000000000000000000..cf12af3dbe09e5ebde56a59e8f1f238837796a03 Binary files /dev/null and b/docs/images/workshops/workshop_2.png differ diff --git a/docs/workshops.md b/docs/workshops.md new file mode 100644 index 0000000000000000000000000000000000000000..57f7990e1299b426ea7c55ac1753714dd22dfee5 --- /dev/null +++ b/docs/workshops.md @@ -0,0 +1,99 @@ + +# Workshops + +Jupyter-JSC provides a dedicated endpoint to facilitate workshops through the Jupyter infrastructure. + +## Motivation + +Organizing workshops can be a complex task. Instructors must coordinate participant access, prepare materials such as presentations and Jupyter notebooks, and ensure that all components run reliably for every participant. Due to the wide range of options available when starting a service, users may inadvertently select incorrect configurations—such as the wrong system, partition, kernel, or Docker image. These misconfigurations may not trigger immediate errors, but they can result in a non-functional or inconsistent runtime environment. + +To address these challenges and streamline the workshop experience, we offer the ability to create a dedicated **Workshop Website**. This site allows instructors to define a controlled environment for their workshop, which can then be shared with participants. + +## Managing Workshops (for Instructors) + +Instructors can visit the [Workshop Manager Website](https://jupyter.jsc.fz-juelich.de/workshopmanager) to configure and manage their workshops. + +<div style="text-align: center;"> + <img src="../images/workshops/manager_1.png" alt="WorkshopManager1" style="width: 90%;"> +</div> + +Each instructor can define a subset of configuration options that are permitted during the workshop. These settings are then made accessible to participants via a unique "Workshop Link." You may edit your workshop configuration at any time. Clicking **"Create"** (or **"Share"** for existing workshops) will provide you with a personalized link to distribute. + +### Workshop ID + +By default, a randomly generated ID is assigned when a new workshop is created. This ID forms the URL for the workshop, such as: + +https://jupyter.jsc.fz-juelich.de/workshops/_id_ + +If you prefer a custom identifier (e.g., `myworkshop2025`), please contact support to enable this feature for your account. + +### Description + +Include a short description of your workshop. This will be displayed on the corresponding workshop page, helping users verify they are on the correct site. + +### Configuration Options + +Each available option includes a checkbox. If a checkbox is **not** selected, users will retain access to **all** available values for that option. To restrict user selection, ensure the checkbox is checked and specify the allowed values. + +<div style="text-align: center;"> + <img src="../images/workshops/manager_2.png" alt="WorkshopManager2" style="width: 50%;"> +</div> + + +#### Dropdown Menus + +For dropdown selections, multiple values may be chosen using **CTRL+Click** or **SHIFT+Click**. At least one value must be selected for the configuration to be valid. If multiple values are selected, a default value can be specified. + +<div style="text-align: center;"> + <img src="../images/workshops/manager_3.png" alt="WorkshopManager3" style="width: 50%;"> +</div> + + +#### Input Fields + +Input fields can be used to enforce specific values (e.g., setting the runtime to 30 minutes or nodes to 1). If the checkbox next to an input field is selected, the defined value will be enforced. If the checkbox is left unchecked, users may input their own value when starting a service. + +<div style="text-align: center;"> + <img src="../images/workshops/manager_4.png" alt="WorkshopManager4" style="width: 50%;"> +</div> + + +### Expert Mode + +Instructors who are part of the **Workshop Instructor** group gain access to additional features, such as: + +- Creating custom workshop IDs +- Activating **Expert Mode** during workshop creation + +Expert Mode enables the selection of multiple services and systems. However, this mode is disabled by default, as it introduces a higher risk of invalid configurations. For instance, selecting both JURECA and JUWELS as systems, but allowing only the partition `dc-cpu` (which is not available on JUWELS), will result in an unusable setup. + +> To join the Workshop Instructor group contact support. + +<div style="text-align: center;"> + <img src="../images/workshops/manager_5.png" alt="WorkshopManager5" style="width: 90%;"> +</div> + + +## Workshop Website + +### User Account is Ready for the Workshop + +If a user account has the necessary access permissions, the workshop website will resemble the regular configuration interface. However, only the options pre-defined by the instructor will be available for selection. + +<div style="text-align: center;"> + <img src="../images/workshops/workshop_1.png" alt="Workshop1" style="width: 90%;"> +</div> + + +### User Account is Not Ready for the Workshop + +If the workshop requires access to HPC systems, user authorization is managed via [JuDoor](https://judoor.fz-juelich.de). If a participant lacks access to the necessary system, project, or partition, the workshop website will display guidance and troubleshooting documentation. + +In case of uncertainties, participants are encouraged to contact their workshop instructor or use the **Support** button located in the website footer. + +<div style="text-align: center;"> + <img src="../images/workshops/workshop_2.png" alt="Workshop2" style="width: 90%;"> +</div> + +> Example of a user account **without** the necessary permissions: +> [https://jupyter.jsc.fz-juelich.de/workshops/systemunavailable](https://jupyter.jsc.fz-juelich.de/workshops/systemunavailable) diff --git a/mkdocs.yml b/mkdocs.yml index f884f32776401f8f9541290f9bac53ef69630032..487866a6a5cee5d032623b17c14ca0311fe2fe65 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,7 +49,7 @@ extra: logo: "images/logo.png" copyright: | - © 2024 Forschungszentrum Jülich | <a href="https://www.fz-juelich.de/en/legal-notice" target="_blank">Legal Notice</a> + © 2025 Forschungszentrum Jülich | <a href="https://www.fz-juelich.de/en/legal-notice" target="_blank">Legal Notice</a> nav: - General: @@ -63,4 +63,5 @@ nav: - Custom Docker Images: users/jupyterlab/customdockerimage/index.md - Repo2Docker ( Binder ): users/jupyterlab/repo2docker/index.md - Useful Tips & Tricks: users/misc.md + - Workshops: workshops.md - Support: support.md