This repository is a template for creating a Jupyter workshop set up on the Surf Research Cloud. The repository contains a folder structure to organize the workshop material, a GitHub Actions workflow to automatically compress the workshop material, and an ansible playbook to automatically transfer the workshop material to the digital workspaces on the Surf Research Cloud. An example workshop that uses this template can be found here.
- Create a new repository using this template repository.
- Add the workshop material to the
workshop-material
folder. - Update the
environment.yml
file with the required packages. - Optionally: Update the
README.md
file with the workshop information. - Create a 'component' and 'catalog item' in the Surf Research Cloud portal, Instructions below.
- Participants of the workshop can be invited to SRAM via email to give them temporary access to the virtual environments.
- Creating a workspace takes less than 5 minutes per workspace + 15 minutes deployment time.
- The workshop material can be edited found in the workshop-material folder. It contains the jupyter notebooks as well as the data used for the workshop.
- The folder playbooks is exclusively dedicated for automated transfer of the course materials to the digital workspaces on SURF Research Cloud. It is automatically updated by the GitHub Actions workflow, so no need to make changes to this folder.
- The
environment.yml
file describes the packages that are required to run the notebooks. The file is used to create a python kernel on SURF Research Cloud that has all the packages installed. By default the kernel will be calledworkshop-kernel
unless you choose a different name. - The
.github
folder contains a GitHub Actions workflow that will automatically update the zippedworkshop-material.zip
whenever there are changes to theworkshop-material
folder.
| .gitignore
| CITATION.cff
| environment.yml
| LICENSE
| README.md
|
+---.github
| \---workflows
| update-course-materials.yml
|
+---playbooks
| | transfer_workshop_material.yml
| |
| \---roles
| \---transfer_workshop_material
| \---tasks
| main.yml
|
\---workshop_material
+---data
| README.md
|
\---notebooks
Intro_Jupyter.ipynb
First make sure that you have an SRAM collaboration for the workshop. For UU researchers, you can request a collaboration by contacting RDM support.
Secondly, add yourself to the src_co_developer
group in the SRAM collaboration.
Follow the instructions here to create a component in the Surf Research Cloud portal.
Use the url of your newly created repository as the source code repository. And for Path playbooks/transfer_workshop_material.yml
as the playbook path.
Follow the instructions here to create a catalog item in the Surf Research Cloud portal. For the components selection, select:
- SRC-OS
- SRC-CO
- SRC-Nginx
- SRC-External plugin
- jupyter
- Custom Packages
- Shared Working Directory
- AND your newly created component
IMPORTANT: In Step 6 you need to Overwrite several parameter settings:
- For
requirements_file_repo_url
andrequirements_file_path
(both used by the Custom Packages component). Check the instructions forCustom Packages
component here and use the url of your newly created repository forrequirements_file_repo_url
andenvironment.yml
forrequirements_file_path
. - For
paths
(used by Shared Working Directory) fill/scratch
After creating the catalog item, you can now select the catalog item when creating a workspace in the Surf Research Cloud portal. Be aware that in order to use the environment, the user would need to select the workshop-kernel
from the kernel dropdown in the Jupyter notebook.