View source for Tutorial or Teaching Labs HowTo

{{Portal|User}}
__TOC__
This page explains how to use Grid'5000 for tutorials/labs, for instance in a teaching course or project at the university, or in thematic schools.

= Forewords about organizing a tutorial or a teaching lab in Grid5000 =

{{Note|text=Although the Grid5000 charter does not explicitly mention tutorials or labs, the use of Grid'5000 for educational purposes is allowed.<br/>
However, some rules apply, and some steps must be carefully followed.}}

First of all, '''using a single account shared between the multiple trainees is not allowed'''. Every trainee must have her own account.

Also, accounts have to be nominative (see below for the required information). Generic accounts are not allowed.

To that purpose, to ease the account creation phase for a large group of trainees, Grid'5000 provides a '''special procedure for a mass account creation'''.

Second, the teacher may consider reserving resources in the platform to ensure trainees will be able to have access to some of them during the lab.

Third, the teacher may consider helping trainees with their first access to the platform, as basic technical knowledge is required for the access setup.

= Trainees accounts creation =

The workflow for the trainees accounts creation is the following:
# Send an email to the Grid'5000 technical team at [mailto:support-staff@lists.grid5000.fr support-staff@lists.grid5000.fr], with the subject ''Tutorial Accounts Creation: ...'', to inform about your wish to create a group of accounts for trainees. In this email, some information has to be provided, '''see the next section'''.
# Prepare a file containing the list of your trainees' first names, last names, and e-mail addresses. See below for an example of such a CSV file.
# Wait for the answer from the Grid'5000 technical team (support staff), that will provide an ''group''/''engine'' name. Connect to a Grid'5000 frontend and use the <code class=command>g5k-create-tutorial-accounts</code> to launch the actual creation of the accounts, using as parameters the provided ''engine'' name and the trainees CSV file your prepared.
Upon the execution of the script, each trainee will receive an email containing the instructions to set up their password and ssh keys.

You may provide to your trainees the following page of instruction: https://www.grid5000.fr/w/Tutorial_or_Teaching_Labs_Trainee_HowTo

Once a trainee will have set their passwords and SSH public keys, their account will be immediately active (only a few minutes may be required for the passwords and the ssh keys to be synchronized to all Grid'5000 sites and servers). No other action will be required of you. 

{{Note|text=Since this workflow create active accounts for your students, you must have their agreement before proceeding. They must accept [https://www.grid5000.fr/w/Grid5000:General_Conditions_of_Use Grid'5000 General condition of use] which details [https://www.grid5000.fr/w/Grid5000:General_Conditions_of_Use#Personal_information how their personal information are used].}}

== Expected information in the e-mail to send to the technical team (support staff) ==

The mass creation of accounts requires a first manual step by the technical team, to set up in the User Management Service of Grid'5000 an account creation automation '''engine''' as well as a '''dedicated group of users''' for the tutorial trainees. 

For that purpose, the technical team needs some information from you. Please send an e-mail to [mailto:support-staff@lists.grid5000.fr?subject=Tutorial... support-staff@lists.grid5000.fr] including the following content:

{{Tutorial_Lab_creation_form}}

The information will be handled by one of the engineers of the technical team.

== Format of the trainees list CSV file ==

You have to create a CSV file containing the information about the trainees. Such a file must be structured as follows:
* one line per trainee
* lines formatted as <code class=replace>first name</code>, <code class=replace>last name</code>, <code class=replace>email address</code>

For example, if you want to create two trainee accounts for ''John Doe'' and ''Carrie Mathison'', a valid CSV file ''list.csv'' should contain:

 John, Doe, john.doe@trainee.unix-lambda.fr
 Carrie, Mathison, carrie.mathison@trainees.univ-lambda.fr

We remind that '''the use of academic e-mail addresses is to be strongly preferred''' to ''gmail'' or any other non-professional services. 

That CSV file will have to be uploaded (scp) to a Grid'5000 frontend for the next step.

== Use g5k-create-tutorial-accounts on the frontend to create accounts ==

Assuming you are connected to Grenoble's frontend and where you uploaded the CSV file named ''list.csv''.

To create the trainees' user accounts, do the following:

{{Term|location=fgrenoble|cmd=<code class="command">g5k-create-tutorial-accounts</code> <code>-f list.csv</code> <code>-e myEngineName</code>}}

{{Warning|text=<code class="command">g5k-create-tutorial-accounts</code> automatically creates active accounts. The operation cannot be undone: accounts cannot be deleted and any modification has to be done manually on every account individually. Therefore, before executing the script, be sure that all the information contained in the CSV file is correct.}}

= Resource reservation =

Depending on your needs, you can reserve Grid'5000 resources in advance.

However, note that you probably don't need to reserve resources in advance if your tutorial occurs during the usage policy restriction period (daytime in Paris timezone) and:
* it does not require many resources 
* it does not require very specific or rare resources
* it does not have many participants

Still, if you want to reserve resources in advance, one strategy is to [[Getting_Started#Advanced_job_management_topics|reserve them as usual in Grid'5000]], and delete your jobs (e.g. using <code class=command>oardel</code>) just before your tutorial begins (if the tutorial duration is long, split by 2, and delete the second reservations later). Another strategy is to use a job of type container for your advance reservation and let students use jobs of type inner (see [[Advanced_OAR#Container_jobs]]).

Please note that you should use your tutorial lab project name when you submit your advance reservations for your tutorial (e.g <code>oarsub --project LAB-20XX-NAME ... </code>) in order to preserve your ability to use your advance reservation rights for your normal usage of Grid'5000 (see [[Grid5000:UsagePolicy#Privilege_levels_table|Privilege levels table]]).

{{Warning|text=If however your advance reservation(s) for your tutorial would absolutely require more resources than allowed by the [[Grid5000:UsagePolicy|Grid'5000 usage policy]], you must request a special usage permission, as described by the procedure detailed in [[Grid5000:SpecialUsage]].}}

= Access to Grid'5000, connection using SSH =

Past experiences show that many problems are related to some difficulties with the connection to Grid'5000 with SSH keys.

To use Grid'5000, trainees '''must''' have basic knowledge of SSH, and especially know how to generate SSH private and public keys and use them to connect to a remote machine. Don't hesitate to spend time at the beginning of the tutorial to explain it. More information on this topic is available at [[SSH]] and [[Getting_Started#Connect_to_a_Grid.275000_access_machine]].

= FAQ =

If this FAQ does not cover one of your questions, do not hesitate to question by mail [mailto:support-staff@lists.grid5000.fr].

== Does every trainee account need to be validated before the trainee can use the platform? ==

Contrary to what is done with the normal workflow using the account creation form, no validation is required when the engine is used. The script <code class="command">g5k-create-tutorial-accounts</code> creates active accounts.

== What do the trainees need to do to get their account ready to use? ==

Created accounts are active right away after the initial procedure, but '''trainees have to create their passwords and provide their SSH public keys''' before being able to connect for the first time. 
Otherwise, they are not able to connect to any of the grid5000 services.

To do so, they received by email an URL that they must open in a web browser. Every trainee must fill the form in the web browser, with a personal password and SSH public key.

== How does the email sent to students look like? ==
Here is a sample of such an email:
 '''Subject:''' [Grid5000-account] Your Grid5000 account was created by ...
 
 Dear <code class=replace>Firstname Lastname</code> (<code class=replace>username</code>), 
 
 You receive this email because your manager (...) requested a Grid5000
 account for you in the context of a tutorial. To get more information about
 Grid5000, see the website: http://www.grid5000.fr.
 
 Your login on the Grid5000 platform is: <code class=replace>username</code>.
 
 The next two steps for you are now to:
 
 1/ Finish setting up your access to the platform by creating a password and an SSH key.
 
    To do so, open the following URL:
    https://public-api.grid5000.fr/stable/users/setup_password?password_token=<code class=replace>XXXXXXXXXXXXXXXXXXXXXX</code>#special.
 
 2/ Read carefully the two following pages:
 
    The Grid5000 getting started documentation (https://www.grid5000.fr/w/Getting_Started),
    which gives important information on how to use the platform.
 
    The Grid5000 usage policy (https://www.grid5000.fr/w/Grid5000:UsagePolicy),
    which gives the rules that MUST be followed when using the platform. Note that any
    abuse will automatically be detected and reported to your manager.

== How does the form the students open to set their passwords and SSH keys look like? ==
Opening https://public-api.grid5000.fr/stable/users/setup_password?password_token=XXXXXXXXXXXXXXXXXXXXXX#special shows:
[[File:UMS tutorial password and ssh key form.png|800px|frameless]]

== My trainees told me they did not receive any email ==

Do the following:
* Check that the email addresses you put in the CSV file are correct.
* Ask the trainees to check their spam box.
* Ask the trainees to reset their password using [[Special:G5KChangePassword]]. This will send a new email to them, with the instruction to reset their password.

== One of my trainees is not able to log in ==

Some possible causes:
* The trainee is not using the correct login. The login is not an email address. He should have received it by email.
* The trainee did not set up the password using the URL received by email.
* The trainee does not remember the password. In that case, the password can reset using [[Special:G5KChangePassword]].

== One of my trainees is not able to ssh the frontend ==

Possible causes:
* The trainee is not using a correct login. The Grid'5000 login may differ from their usual login when using a workstation or another platform. In that case, the trainee can use the <code class="command">-l </code><code class="replace">G5K_USERNAME</code> option in the SSH command.
* The trainee did not set their SSH private key in the machine (workstation) where the connection to Grid'5000 is made from.
* The trainee did not set up an SSH key when they used the URL to set up their password. To fix this, the trainee can connect to [https://api.grid5000.fr/stable/users/ UMS], click on the left panel ''SSH keys'', and then copy/paste their '''public SSH key'''.

Note that one cannot connect to the Grid'5000 frontends directly (e.g. <code class="host">fgrenoble.grenoble.grid5000.fr</code>). One first needs first to connect to the access machine: <code class="host">access.grid5000.fr</code>.

To avoid the two-steps connection (access machine, then frontend) and connect directly to frontends, one can configure the SSH config file <code class=file>~/.ssh/config</code> as follows:

 Host g5k
   User <code class="replace">G5K_USERNAME</code>
   Hostname access.grid5000.fr
   ForwardAgent no
 Host *.g5k
   User <code class="replace">G5K_USERNAME</code>
   ProxyCommand ssh g5k -W "$(basename %h .g5k):%p"
   ForwardAgent no

Then,
* Accessing the frontend (here, of Grenoble) can be done with:
 ssh grenoble.g5k

From there, resources access is managed with the Grid'5000 tools (OAR commands and so on). See the [[Getting Started]] tutorial.

== What happens if one of my trainees already has a Grid5000 account? ==

This case is covered by the procedure: the CSV file can and must contain the email addresses of trainees that already have an account.

; Several cases then:
* If the existing account is active, the account is just added in the group of the tutorial/lab.

* If the existing account is retired, the account is re-activated before being added to the groups of the tutorial/lab as above.

* However, if the existing account is locked, it needs an intervention from support-staff. For the record, an account can be locked for one of these two reasons: its email address bounces (mostly because invalid), or the user was sanctioned for a misuse of the platform.

* Last, by running the script it may happen that you create a new account for a trainee that already had one, that because the email address you provided for a trainee differs from the one of the trainee's existing account. The trainee may want to use their existing account rather than the new one you created. In that case, you can just run again the script with a CSV containing only one line with the information about that trainee, but changing the email address to that of the previously existing account of the trainee.

== The g5k-create-tutorial-accounts script returned an error for one of trainee ==

If you get an error, please contact [mailto:support-staff@lists.grid5000.fr support-staff].

= List of the tutorials/labs using Grid5000 =

{{Note|text=If you indeed organize a tutorial which uses Grid5000, we kindly ask it to be recorded in the list below.}}

; The following list contains the tutorials already organized on Grid'5000
* Un TP à l'IMT Atlantique 'FIL A3 Back/FIL A3 Back' sur le déploiement d'Openstack, pour des étudiants de master, organisé en octobre 2022 par Baptiste Jonglez et Adrien Lebre.
* Un TP pour le GDS CNRS EcoInfo. Un après midi de mesures énergétiques sur le site de Lyn et éco-conception logicielle, organisé en octobre 2022 par Laurent Lefevre (ENS/LIP/Avalon).
* Un TP en Master 1 TAL à l'Université de Lorraine / IDMC. Introduction à Grid5000, en 2020-2021-2022.
* Un TP en Master 1 Informatique à l'Université de Lille, depuis 2010. Initiation à un environnement et des paradigmes de calcul distribué: réservation de machines et déploiement (oar/kadeploy), traitement d'applications Embarrassingly parallel en mode batch, programmation MPI, expérimentation, scalabilité et mesure de performance. Un groupe d'une vingtaine d'étudiants environ. 3 séances de TP environ.
* Un TP à Rennes, avec Nikos Parlavantzas et une intervention dans le master MRI (1 cours, 2 TP par D. Margery, années 2013-2014, 2014-2015 et 2015-2016. Repris par Matthieu Simonin depuis))
* Un TP au cours de http://sc-camp, en 2011
* Un TP à l'ENS Lyon (TP OpenStack aux master 2)
* Un TP à l'ENS Lyon (12/2013) sur OpenCL (''Sujet'' [http://perso.ens-lyon.fr/arnaud.lefray/enseignement/])
* TP à l'ENS Lyon (2014-2015)  "Distributed Systems" M1 course
* Un projet, sur 8 semaines, à l'Ensimag (Grenoble-INP) (automne 2015, automne 2016) "Systèmes distribués et Cloud Avancé" (enseignant: Grégory Mounié), une cinquantaine d'élèves de niveau M2, groupés en 12 équipes
* Un projet de Licence 3 informatique à l'Université de Montpellier  (semestre pair 2016) "Prise en main d’OpenStack et mise en oeuvre d'un outil de déploiement d'applications simples sur des VMs" ) groupe de 4 étudiants, encadré par Hinde Lilia Bouziane.
* Un TP en Master 2 à l'Université de Montpellier, décembre 2016, octobre et novembre 2017, novembre 2018 dans le cadre d'un cours "E-applications". Il s'agit d'un TP d'initiation à l'utilisation d'une plateforme distribuée : réservation de machines, exécution d'une application à distance et importation des résultats. Une trentaine d'étudiants répartis en deux groupes en 2016, une cinquantaine d'étudiants en 2017 et une quarantaine en 2018. TP encadré par Hinde Lilia Bouziane.
* Un projet de Licence 3 informatique à l'Université de Montpellier, de novembre 2017 à juin 2018 (groupe de 2 étudiants). Le projet porte sur la programmation d'un traitement parallèle et distribué d'images. Projet encadré par Hinde Lilia Bouziane.
* Un TP à l'IMT Atlantique (campus de Nantes) de 4 étudiants encadré par Mario Südholt de octobre 2018 à janvier 2019.
* Un projet de Master 1 informatique à l'Université de Montpellier, de janvier à juin 2019 (groupe de 3 étudiants). Résumé "Nous disposons d'un algorithme d'apprentissage de relations sémantiques basé sur les relations existantes dans le réseau lexical du JeuxDeMots (http:www.jeuxdemots.org). La table générée est de grande taille, de l'ordre de plusieurs centaines de millions de lignes. L'objectif du projet est de distribuer cette table et de mettre en ouvre un algorithme d'apprentissage et d'exploitation de manière distribuée et parallèle.". Projet encadré par Hinde Bouziane et Mathieu Lafourcade.
* Un projet de Master 1 informatique à l'Université de Montpellier, de janvier à juin 2019 (groupe de 2 étudiants). Le projet porte sur la programmation d'un traitement parallèle et distribué d'images (photogrammétrie). Projet encadré par Hinde Lilia Bouziane.
* Un projet "deep learning" en [http://formations.univ-grenoble-alpes.fr/fr/catalogue/master-XB/sciences-technologies-sante-STS/master-informatique-program-master-informatique/parcours-genie-informatique-alternance-2e-annee-subprogram-parcours-genie-informatique-m2-alternance/ue-documents-multimedia-description-et-recherche-automatique-IFQV03ZG.html M2 GI] et [http://formations.univ-grenoble-alpes.fr/fr/catalogue/cycle-preparatoire-et-diplome-d-ingenieur-XC/sciences-technologies-sante-STS/ingenieur-de-polytech-grenoble-specialite-informatique-reseaux-informatiques-et-communication-multimedia-program-ingenieur-de-polytech-grenoble-specialite-reseaux-informatiques-et-communication-multimedia/ue-texte-et-donnees-text-and-data-IH1TB9TW/acces-et-recherche-d-information-information-retrieval-IH1TD4T4.html Polytech INFO4] à l'université de Grenoble, de février à avril de 2019 à 2023 inclus. Projet encadré par Georges Quénot.
* TP de l'UE Parallélisme, du M1 de l'UCBL (Simon Delamare), 2019-2020
* TP de l'Université de Lille, M2 Data Science, MPI & GPU (Pierre Fortin), 2020-2021
* TP Ensimag 3A ISI, systèmes distribués (Grégory Mounié), 2020-2021 
* TP de la filière MOSIG de l'UGA, calcul parallèle (Arnaud Legrand, Bruno Raffin, Frédéric Wagner), 2020-2021.
* TP de l'Université de Montpellier : dans le cadre d'un cours "E-applications" de Master 2, initiation à l'utilisation d'une plateforme distribuée partagée : réservation de machines, exécution d'une application à distance et importation des résultats. Deux groupes de 25 étudiants (Hinde Bouziane), 2020
* TP pour le Groupe Calcul, introduction à Grid'5000 (Simon Delamarre), 2020
* TP de l'Université de Lille, 5ème année de la spécialité Informatique et statistiques (IS5) à Polytech Lille. Teaching labs on GPU programming. Module CHP (Calcul Haute Performance). 2 sessions de 2 heures (Pierre Fortin), 2020-2021
* TP de Sorbonne Université, UFR d'ingénierie, Master d'informatique M1, parcours SFPN, Introduction au Calcul Haute-Performance, Charles Bouillaguet, 2020-2021
* TP de ENS de Rennes, Master informatique, Module Cloud and Big Data, Anne-Cécile Orgerie et Shadi Ibrahim, 2015-2021
* TP de l'UCBL, Master 1 Informatique, UE Parallélisme, Simon Delamare, 2020-2021
* Tutorial "Installation, deployment and execution of Melissa; Understanding how to port an existing application into the Melissa framework", Bruno Raffin INRIA-DATAMOVE/LIG, 16 septembre 2021.
* TP d'introduction à Grid5000 de l'Université de Lorraine (IDMC), Chuyuan Li, 22 septembre et 1er octobre 2021
* Hackathon pour [https://rsd-ecole.cnrs.fr/ l'école automnale RESCOM de recherche du GDR RSD] (Bruno De moura Donassolo, Arnaud Legrand, Matthieu Simonin), 4-8 octobre 2021.
* TP de l'Université de Lille, 5ème année de la spécialité Informatique et statistiques (IS5) à Polytech Lille. Teaching labs on GPU programming. Module CHP (Calcul Haute Performance), Pierre Fortin, 2020-2021
* TP de l'Université Grenoble-Alpes, INPG/Master Recherche MOSIG, Calcul Parallèle, Bruno Raffin & Frédéric Wagner, 2020-2021.
* TP de l'université Aix Marseille, L3 Informatique, Impact du numérique, Julien Lefevre, 2021-2022
* TP de Sorbonne Université, UFR d'ingénierie, Master d'informatique M1, parcours SFPN, Introduction au Calcul Haute-Performance, Charles Bouillaguet, 2021-2022
* TP de LS2N, Membre de LS2N UMR à Nantes, Teaching the fundamentals of Grid'5000 platform for beginner users only for internal members of LS2N, Richard RANDRIATOAMANANA & Remous Aris KOUTSIAMANIS, 26-Jan 2022
* TP de CY Paris Université, Master2 student, Heterogeneous programming on GPU (CUDA), Thierry Garcia, 22-Mar 2022
* Tutoriel sur l'utilisation de la plateforme Grid'5000 dans le cadre du groupe de travail "plateformes" du GDR RSD, Simon Delamare et Pierre Jacquot, Mars 2022
* TP de l'UCBL, Master 1 Informatique, UE Parallélisme, Simon Delamare, 2022
* TP et petits projets de Sorbonne Université, Master’s in High Performance Computing (HPC), Parallel programming (PPAR), Charles Bouillaguet, 2022-2023
* Un projet d'ingénierie sur le thème Lab on energy consumption - ANF User Support Tools for HPC 2023 organisé en juin 2023 par Mathilde Jay
* Un TP à l'UCBL (Lyon 1) pour le Master informatique "TP développement d'applications parallèles hybrides, évaluation et analyse de leurs performances", d'avril à juin 2023.
* Un projet à CY Tech Campus de Pau intitulé Project and simulation on GPU using CUDA facilities en M2 organisé de janvier à mars 2023 par Thierry Garcia
* Un TP à UGA pour le Master Recherche MOSIG en 'Advanced Parallel System' de janvier à mars 2023 organisé par Bruno Raffin
* TP et petits projets de Sorbonne Université, Master’s in High Performance Computing (HPC), Parallel programming (PPAR), Charles Bouillaguet, 2023-2024
* TP Virtualisation Système et Réseau, FSI Master Informatique parcours SECIL spécialité Réseaux et Systèmes Distribués, Virtualisation Système et Réseau, Millian Poquet, 2023
* TP de l'Université Grenoble-Alpes, Master2 MIAGE, "EcoWeb : Study the energy consumption of the various components of a host", Mathilde Jay, Octobre 2023