Merge pull request #206 from SouthernMethodistUniversity/cf_docs

Current docs, including ColdFront in toc

docs/_config.yml

@@ -5,3 +5,11 @@ execute:
   execute_notebooks: "off"
 html:
   favicon: "./images/favicon.ico"
+parse:
+  myst_enable_extensions:
+    - colon_fence
+    - dollarmath
+    - linkify
+    - substitution
+    - tasklist
+    - html_image

docs/_toc.yml

@@ -14,6 +14,16 @@ parts:
   - file: portal.md
   - file: m3_migration.md
   - file: mp_update.md
+- caption: ColdFront
+  chapters:
+  - file: coldfront/quick_start.md
+    sections:
+    - file: coldfront/qs_instructor.md
+    - file: coldfront/qs_student.md
+  - file: coldfront/add_change_project.md
+  - file: coldfront/add_class.md
+  - file: coldfront/add_remove_users.md
+  - file: coldfront/request_change_allocation.md
 - caption: Applications
   chapters:
   - file: examples/chemistry.md

docs/coldfront/add_change_project.md

@@ -45,10 +45,10 @@ Only benefits eligible faculty or staff can create a project.
     :width: 800px
     ```
 
-6. Select all relevant Fields of Science.
+6. Select all relevant Fields of Study.
 
     ```{image} 
-    :alt: fields of science
+    :alt: fields of study
     :width: 800px
     ```
 
@@ -68,27 +68,12 @@ Only benefits eligible faculty or staff can create a project.
 
 9. Please read and acknowledge that you will follow the ODSRCI Community Guidelines.
 
-10. Click Save to create the project.
-
-    ```{image} ../images/CF/add_change_project/save.png
-    :alt: save
-    :height: 40px
-    ```
+10. Click <img src="../images/CF/add_change_project/save.png" alt="Save" height="40"> to create the project.
 
 ## Change a Project
 
-1. From the project page, click on
-
-    ```{image} ../images/CF/add_change_project/update_project.png
-    :alt: update project information
-    :height: 40px
-    ```
+1. From the project page, click on <img src="../images/CF/add_change_project/update_project.png" alt="update project information" height="40">.
 
 2. Change any relevant information for Title, Description, Field of Science, and Departments.
 
-3. Click on
-
-    ```{image} ../images/CF/add_change_project/save.png
-    :alt: save
-    :height: 40px
-    ```
+3. Click on <img src="../images/CF/add_change_project/save.png" alt="save" height="40">.

docs/coldfront/add_class.md

@@ -0,0 +1,85 @@
+# Add a Class
+
+```{note}
+Only benefits eligible faculty or staff can create a class.
+```
+
+These instructions will help you get access to HPC resources for your class.
+If you are the instructor of record in my.smu, much of this process will be easy and automated for you.
+If you are not an instructor of record for a course but would like to set up a course (e.g. workshop or bootcamp), 
+please reach out to [[email protected]](mailto:help%40smu.edu?subject=%5BHPC%5D) and include [HPC] in the subject line.
+
+### Setting up your class
+
+```{image} ../images/CF/quick_start/add_class.png
+:alt: add a class button
+:width: 400px
+```
+
+1. Login to ColdFront via SSO with your SMU credentials
+2. Select Add a class 
+3. Select your course from the drop down menu
+4. Select which sections you would like to have access to HPC resources
+5. Mark which additional options you need
+6. Select Save once complete.
+
+Once a class is created you will have options to Add additional users and request additional allocations.
+
+### To add Students and Other Users
+
+For classes, the management of students is synched hourly with class enrollment records starting a week before the semester starts.
+Once in the , students that add or drop will be added or removed from your class and allocations accordingly.
+
+```{note}
+All students will appear 7 days before the semester begins.
+```
+
+If you wish to add a user who is not enrolled to your class (e.g. a co-instructor), follow the steps below.
+
+```{note}
+This is not especially common. Do not add students that will be enrolled in the course as this could disrupt their file permissions.
+```
+
+1. Once your class is created, select Add Users within the Users section of your class
+
+    ```{image} ../images/CF/quick_start/add_users.png
+    :alt: add users
+    :width: 400px
+    ```
+
+2. If you are searching by “Exact Username Only” search for the user via SMU email alias
+
+    ```{note}
+    If you are adding multiple users, you can list them all in the Search String box
+    ```
+
+3. If you are searching by “All Fields” you can enter last name or SMU email alias
+
+4. Once you’ve found and selected the user(s), select the role the user should have
+
+    ```{image} ../images/CF/quick_start/user_role.png
+    :alt: user role
+    :width: 100px
+    ```
+
+5. Then Add Selected Users to Project
+6. Once complete you will see all users requested under the Users section
+
+### To Request Additional Resource Allocations
+
+All classes are granted a default compute allocation consisting of ***Core Usage (Hours)*** and ***Memory Usage (Hours)***.
+Depending on the options chosen at the creation of the project, this may contain ***Accelerator Usage (Hours)*** or a second allocation for Storage.
+The Storage allocation is Read-Only for students by default.
+
+If you find your class needing additional resources, you can request additional allocations for either Compute or Storage, by following the instructions below.
+
+```{image} ../images/CF/quick_start/request_resource_allocation.png
+:alt: request resource allocation
+:width: 200px
+```
+
+1.	Next to Allocations, Select the **+Request Resource Allocation button**
+2.	Complete all required fields
+3.	Select the users you’d like to add to this allocation
+4.	Select Submit
+5.	Once complete you will see your status request as **Pending Review** under Allocations

docs/coldfront/add_remove_users.md

@@ -17,12 +17,7 @@ Instructors and PI's are automatically assigned the ***Manager*** role within a
 
 ### To a Project/Class
 
-1. Once a project or class is created, under Manage Project, click on
-
-    ```{image} ../images/CF/add_remove_users/add_users.png
-    :alt: add users
-    :height: 35px
-    ```
+1. Once a project or class is created, under Manage Project, click on <img src="../images/CF/add_remove_users/add_users.png" alt="add users" height="35"/>
 
 3. Type in usernames of the user(s) you would like to add separated by a space or on separate lines.
 
@@ -36,21 +31,16 @@ Instructors and PI's are automatically assigned the ***Manager*** role within a
     :height: 150px
     ```
 
-4. Click on
+4. Click on <img src="../images/CF/add_remove_users/search_button.png" alt="search button" width="700"/>
 
-    ```{image} ../images/CF/add_remove_users/search_button.png
-    :alt: search button
-    :weight: 700px
-    ```
-
-    ```{note}
+    ````{note}
     If a user has already been added to the project or class, then you will see a message like this
     ```{image} ../images/CF/add_remove_users/user_already_added.png
     :alt: user already added message
     :height: 35px
     :align: center
     ```
-    ```
+    ````
 
 5. Select the user(s) that you want to add from the list 
 
@@ -66,12 +56,7 @@ Instructors and PI's are automatically assigned the ***Manager*** role within a
     :height: 60px
     ```
 
-6. Click on
-
-    ```{image} ../images/CF/add_remove_users/add_selected_users.png
-    :alt: add selected users
-    :height: 35px
-    ```
+6. Click on <img src="../images/CF/add_remove_users/add_selected_users.png" alt="add selected users" height="35">
 
 7. You can verify that a user has been added under Users on the Project/Class page.
 
@@ -91,9 +76,7 @@ When [requesting an allocation](https://southernmethodistuniversity.github.io/hp
 
     <img src="../images/CF/add_remove_users/select_user.png" alt="select users" height="60"/>
 
-3. Click on
-
-    <img src="../images/CF/add_remove_users/remove_selected_users.png" alt="remove selected users" height="40"/>.
+3. Click on <img src="../images/CF/add_remove_users/remove_selected_users.png" alt="remove selected users" height="40"/>.
 
 4. You can verify that a user has been removed under <img src="../images/CF/add_remove_users/users.png" alt="users header" height="35"/> on the Project/Class page.
 
@@ -109,8 +92,6 @@ When [requesting an allocation](https://southernmethodistuniversity.github.io/hp
 
     <img src="../images/CF/add_remove_users/user_role_change.png" alt="change user role" height="40"/>
 
-3. Click on
-
-    <img src="../images/CF/add_remove_users/update.png" alt="update user" height="40"/>
+3. Click on <img src="../images/CF/add_remove_users/update.png" alt="update user" height="40"/>
 
 ### Allocation Permissions

docs/coldfront/qs_instructor.md

@@ -0,0 +1,133 @@
+# Getting Started in ColdFront as an Instructor
+
+These instructions will help you get access to HPC resources for your class.
+If you are the instructor of record in my.smu, much of this process will be easy and automated for you.
+If you are not an instructor of record for a course but would like to set up a course (e.g. workshop or bootcamp), 
+please reach out to [[email protected]](mailto:help%40smu.edu?subject=%5BHPC%5D) and include [HPC] in the subject line.
+
+## Setting up your class
+
+```{image} ../images/CF/quick_start/add_class.png
+:alt: add a class button
+:width: 400px
+```
+
+1. Login to ColdFront via SSO with your SMU credentials
+2. Select Add a class 
+3. Select your course from the drop down menu
+4. Select which sections you would like to have access to HPC resources
+5. Mark which additional options you need
+6. Select Submit once complete.
+
+Once a class is created you will have options to Add additional users and request additional allocations.
+
+## To add Students and Other Users
+
+For classes, the management of students is synched hourly with class enrollment records starting a week before the semester starts.
+Once a class is requested in ColdFront, students that add or drop will be added or removed from your class and allocations accordingly.
+
+```{note}
+All students will appear 7 days before the semester begins.
+```
+
+If you wish to add a user who is ***not*** enrolled to your class (e.g. a co-instructor), follow the steps below.
+
+```{note}
+This is not especially common. Do not add students that will be enrolled in the course as this could disrupt their file permissions.
+```
+
+1. Once your class is created, select Add Users within the Users section of your class
+
+    ```{image} ../images/CF/quick_start/add_users.png
+    :alt: add users
+    :width: 400px
+    ```
+
+2. If you are searching by “Exact Username Only” search for the user via SMU email alias
+
+    ```{note}
+    If you are adding multiple users, you can list them all in the Search String box
+    ```
+
+3. If you are searching by “All Fields” you can enter last name or SMU email alias
+
+4. Once you’ve found and selected the user(s), select the role the user should have
+
+    ```{image} ../images/CF/quick_start/user_role.png
+    :alt: user role
+    :width: 100px
+    ```
+
+5. Then Add Selected Users to Project
+6. Once complete you will see all users requested under the Users section
+
+## In Class
+
+Once you are ready for your students to use the resources, have them go to [hpcaccess.smu.edu](hpcaccess.smu.edu) and log in to ColdFront.
+They will see your class and associated allocations on their dashboard. They will need to click on your class to be taken to the class page.
+
+Under Allocations, they will see a button for **Review and Accept Policies and Guidelines to activate** for to each allocation.
+They will need to accept the Policies and Guidelines for each allocation in order to get access the those resources.
+
+```{note}
+Once a student is in a course and accepts the Policies and Guidelines, they will be granted an HPC account.
+In most cases this process is instantenous, however if you have a large number of files in a storage allocation for a class, this could take several minutes.
+```
+
+If you are using the Open OnDemand portal [hpc.smu.edu](hpc.smu.edu) for your course, students will be able to click on the link in the top menu bar to go directly to the M3 Portal.
+
+If you are using `srun` commands or `sbatch` scripts, your students will need to add the following to their commands/scripts in order to utilize the resources.
+
+`#SBATCH -A slurm_account_name`
+
+or
+
+`srun -A slurm_account_name …`
+
+The `slurm_account` can be found in the Information field under Allocations.
+
+```{image} ../images/CF/quick_start/resource_table.png
+:alt: resource table
+:width: 800px
+```
+
+## To Request Additional Resource Allocations
+
+All classes are granted a default compute allocation consisting of ***Core Usage (Hours)*** and ***Memory Usage (Hours)***.
+Depending on the options chosen at the creation of the project, this may contain ***Accelerator Usage (Hours)*** or a second allocation for Storage.
+The Storage allocation is Read-Only for students by default.
+
+If you find your class needing additional resources, you can request additional allocations for either Compute or Storage, by following the instructions below.
+
+```{image} ../images/CF/quick_start/request_resource_allocation.png
+:alt: request resource allocation
+:width: 200px
+```
+
+1.	Next to Allocations, Select the **+Request Resource Allocation button**
+2.	Complete all required fields
+3.	Select the users you’d like to add to this allocation
+4.	Select Submit
+5.	Once complete you will see your status request as **Pending Review** under Allocations
+
+
+## To view your current usage
+
+1.	Under Allocations select the folder icon
+2.	You will see your Allocation details, Policies and Guidelines Agreements, and Usage by Hours
+
+
+## Concluding the Semester
+
+At the end of the semester, your class will be Archived.
+Once you class is successfully archived, you will not be able to make any changes but will still be able to view some details at any time
+
+## To view Archive Projects
+
+1.	After logging into ColdFront, select Projects> Projects
+2.	Top right of your page, you will see View Archived Projects
+
+    ```{image} ../images/CF/quick_start/view_archived.png
+    :alt: view archived
+    :width: 200px
+    ```