Using JupyterHub for Instruction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c3c0c2d3",
   "metadata": {},
   "source": [
    "<div>\n",
    "<img src=\"img/libraries_short_color.png\" width=\"350\" align=\"right\" alt=\"The NYU Libraries Logo.\"/>\n",
    "</div>\n",
    "\n",
    "# An Introduction to JupyterHub for Instruction\n",
    "\n",
    "Lesson plan developed by Shreemayi Sonti, Nicholas Wolf, Wasif Hyder, and Andrew Brackett\n",
    "\n",
    "NYU Data Services | NYU Teaching & Learning\n",
    "\n",
    "This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.\n",
    "\n",
    "### Overview\n",
    "\n",
    "This session is designed for instructors and teaching assistants who need an introduction to the JupyterHub environment, an overview of the specifics of NYU's installation of JupyterHub, or just need a refresher on the helpful capabilities of the system. It presumes you have at least a general familiarity with Jupyter projects, particularly the Jupyter Notebook (if not, see our guide to Notebooks: https://guides.nyu.edu/data_management/jupyter-notebooks).\n",
    "\n",
    "Among the goals are to teach:\n",
    "\n",
    " - The advantages in terms of delivering class materials and a coding environment using JupyterHub\n",
    " - How to set up the JupyterHub environement for sharing files and using autograders\n",
    " - Examples for how to leverage JupyterHub for interesting teaching\n",
    " - How to find helpful resources and answer questions about NYU's instance of JupyterHub\n",
    "\n",
    "\n",
    "### Class Materials\n",
    "\n",
    "**Lesson Plan**\n",
    "\n",
    "This notebook is available to preview in static form at [this link](https://github.com/NYU-DataServices/JupyterHub-Instructors/blob/main/Using%20JupyterHub%20for%20Instruction.ipynb). You can download the file by cloning the notebook as follows:\n",
    "\n",
    "<code>git clone https://github.com/NYU-DataServices/JupyterHub-Instructors.git</code>\n",
    "\n",
    "**Class JupyterHub**\n",
    "\n",
    "You can access this lesson plan to run the code live at [https://tutorials-1-spring-instructor.rcnyu.org](https://tutorials-1-spring-instructor.rcnyu.org)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1e3f60c",
   "metadata": {},
   "source": [
    "<div>\n",
    "<img src=\"https://upload.wikimedia.org/wikipedia/commons/3/38/Jupyter_logo.svg\" width=\"150\" align=\"right\" style=\"padding: 20px\" alt=\"The Jupyter project logo.\"/>\n",
    "</div>\n",
    "\n",
    "## 1.0 What is JupyterHub?\n",
    "\n",
    "JupyterHub is an open-source distribution of software that can be deployed on a server so that multiple users can access Jupyter Notebooks (nb) and other Jupyter applications from a web browser. It not only enables users to collaborate and work in teams, but also provides an option to scale up/down the resources as and when needed. Admins (and instructors to a certain extent) can add a layer of authentication and control access to all the resources. This feature of customization makes JupyterHub a useful application in educational or research settings where Jupyter Notebooks are used concurrently.\n",
    "\n",
    "The advantages of using JupyterHub to teach include:\n",
    "\n",
    " 1. All students in a couse obtain access to a baseline sufficient environment to perform coursework (i.e. they aren't limited by the size/expense of their local machine).\n",
    " 2. Instructors can provide the same environment for all students, rather than troubleshoot multiple local installations on varying operating systems, etc.\n",
    " 3. Jupyter Notebooks offered on a shared JupyterHub coursesite can take advantage of all the interactive and web-first design elements, combining runnable code and instructional text in a way that a code-only or a text-only environment cannot.\n",
    " 4. It allows students to practice writing code in a realistic work environment that they are likely to encounter in a future workplace.\n",
    " 5. Instructors can take advantage of \"high-end\" options such as connecting Notebooks to databases or using it in conjunction with Spark to enable a computationally advanced environment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e756c116",
   "metadata": {},
   "source": [
    "## 2.0 Setting Up\n",
    "\n",
    "### 2.1 Kernels and Packages\n",
    "\n",
    "Environments are managed on the NYU JupyterHub instance using <code>conda</code>, and is done via opening a terminal session in the launched JupyterHub system. The option to start a terminal session is located in the \"New+\" menu to the right:\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/opening-terminal-screen.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of where to find the terminal session creation option in the New menu of the main JupyterHub dashboard screen. An arrow points to the terminal option under the dropdown of that menu.\"/>\n",
    "</div>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "Step-by-step instructions for how to create a new environment and install packages (either via the Anaconda package channel or pip and PyPi) can be found in the \"Software\" tab of your JupyterHub settings webpage (located at either https://settings-spring.rcnyu.org or https://settings-fall.rcnyu.org, depending on the semester).\n",
    "\n",
    "Once a new environment is created, the environment and its installed packages will be available by selecting it as a kernel in the Kernel >> Change Kernel menu in any Jupyter Notebook. The selected kernel will be displayed at the top right of the noteook:\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/selecting-kernel-screen.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of where to find the option to select a kernel and environment created by the instructor. An arrow points to the Change Kernel option under the dropdown of the Kernel menu, and a second arrow indicates where the current activated kernel can be found.\"/>\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4570fc4d",
   "metadata": {},
   "source": [
    "### 2.2 Instructor Settings\n",
    "\n",
    "By accessing the JupyterHub \"Settings\" tab, instructors can control the following:\n",
    "\n",
    " - Modifying access. Instructors can add/remove students/instructors to the class can be done by using Settings >> User Lists on the settings site. The allow list is for students, and instructor list is for instructors/TAs. Make sure to “Apply all settings now” to persist the changes made.\n",
    "\n",
    " - RAM, Storage, and GPU can be adjusted throughout the semester by selecting the preferred setting. However, request from the JupyterHub team only as much of each as is needed, raising the allocation temporarily for certain assignments and then dropping it down. \n",
    " \n",
    " - Default IDE can be set to either ClassicNotebook/ JupyterLab/ RStudio. Instructors can also add features like MySQL/ MongoDB / or any additional software to run the code on Jupyter Hub. Note especially the direct links to various editors, e.g. <code>/tree</code>, <code>/lab</code>, etc.\n",
    "\n",
    "Most students will need persistent storage for semester-long courses, otherwise their files will not be available from session to session. When a GPU option is enabled, the students will see a third option other than general or turbo mode at initial start up."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffcf3ee0",
   "metadata": {},
   "source": [
    "### 2.3 Three Options for Managing Shared Files\n",
    "\n",
    "There are three main ways to share files with students. The best option to select is based on whether the files need to be shared with the entire class, with just a sub-group of students, or as part of an assignment.\n",
    "\n",
    "Note that particularly if your students will need to write scripts against larger files, it is much better to offer those files via a shared folder than to have the students upload their own copy of that large file in their own root. Students typically have 1-2 GB of storage in their instance, making it very easy for them to fill up that storage.\n",
    "\n",
    "Instead, consider one of the following options:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83e1c25e",
   "metadata": {},
   "source": [
    "### 2.3.1 Use the Shared Folder\n",
    "\n",
    "Found in the root of all instances (instructor and students), this is a read-only folder for students. Instructors, on the other hand, have read/write access and can upload data by switching to the <code>\\~\\/shared</code> directory and uploading/modifying/deleting data. Every change here will be visible to all the students in their <code>\\~\\/shared</code> directory.\n",
    "\n",
    "### 2.3.2 Use the Group Share Feature\n",
    "\n",
    "Follow the instructions found in the JupyterHub settings webpage under the tab \"Group Work\", summarized as follows:\n",
    "\n",
    "Step 1: Using the instructor instance of Jupyter Hub server, open terminal and create new directories within ~/groupshare folder, labeling the end of each folder with a random set of numbers or digits. Build as many folders as you intend to have groups. You may use the following commands as each group should get a unique folder name:\n",
    "\n",
    "- Create a random string that will serve as an ID\n",
    "        <code>randString=$(openssl rand -hex 32)</code>\n",
    "- Create a folder for a group with the ID\n",
    "       <code>mkdir ~/groupshare/group_1_$randString/</code>\n",
    "- Give permissions for students to read, write and execute files in that folder\n",
    "        <code>chmod 777 ~/groupshare/group_1_$randString/</code>\n",
    "- You can always see the directories you’ve created on the instructor site in the UI or type ls into the terminal. Students from their student servers cannot see any folders in this directory without knowing the exact address of the folder.\n",
    "\n",
    "Step 2: Send the directory path for a specific group folder to all group members, so they can access and contribute to their group work.\n",
    "\n",
    "- Inform students they need to read/write in their scripts to the folder using the terminal. (Example: ~/groupshare/group_1_0dfb69f079)\n",
    "- Students can also open the directory directly by adding the path you share after the “tree” stem of their JupyterHub URL. (Example: …tree/groupshare/group_1_0dfb69f079).\n",
    "\n",
    "Important considerations and limitations:\n",
    "\n",
    "- Access control is done purely based on sharing/not-sharing the name of the directory with students.\n",
    "- This directory is designed to share scripts, not data. Large data files should not be placed in groupshare. Instead, students should still ask their TA or instructor to upload a large file to the class shared directory.\n",
    "- Overall groupshare directory is limited to 10GB for all groups combined, and students have read/write access to this directory. If one group takes all the space, other groups will not be able to store anything. Instructors and TAs can always look into groupshare directory using the instructor site to see who is using too much storage. Please contact the JupyterHub team if you need to request more group share storage.\n",
    "- Files which students put into this directory do NOT count against a student’s home directory storage quota.\n",
    "\n",
    "### 2.3.3 Accessing Files as Part of an Assignment\n",
    "\n",
    "This option is available when setting up an assignment as explained below. By fetching these assignments, students will receive a copy of these files in their memory. Students will be able to edit and submit files using this approach.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01e88abb",
   "metadata": {},
   "source": [
    "## 3.0 Creating Assignments Using NBGrader\n",
    "\n",
    "JupyterHub has the nbgrader package pre-installed, which has functionality for releasing, collecting, grading, and providing feedback for students conveniently.\n",
    "\n",
    "In addition to the resources below, note that nbgrader itself has a good set of supporting resources. Check out:\n",
    "\n",
    " - [Official docs](https://nbgrader.readthedocs.io/en/stable/)\n",
    " - [Github homepage](https://github.com/jupyter/nbgrader)\n",
    " - [Parts 2](https://youtu.be/yth_5wCcCCA) and [Parts 3](https://youtu.be/QoAsVvpDlXg) of this series by @Willy PChem\n",
    "\n",
    "### 3.1 Steps to Create an Assignment\n",
    "\n",
    "**1. Add a new assignment**\n",
    "\n",
    "Go to the \"Formgrader\" tab from the main JupyterHub dashboard and select the \"+ add new assignment\" at the end of the list on the on manage assignments page.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-1.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the assignments dashboard with an arrow pointing out the add assignments button at the bottom of the assignment list.\"/>\n",
    "</div>\n",
    "\n",
    "Name the assignment and set the due date (optional). A folder with the same name as the assignment gets created inside the “source” folder of files on JupyterHub.\n",
    "\n",
    "**2 Create notebook for assignment and set options**\n",
    "\n",
    "Click on the newly created assignment formgrader assignments, you will be taken to the newly created folder.\n",
    "\n",
    "Create a new notebook with the relevant kernel in this folder and provide a name to it.\n",
    "\n",
    "To edit the notebook with nbgrader, switch to \"create assignment\" mode.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-2.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of an assignment notebook webpage, showing how to turn the notebook into an assignment by selecting create assignment under the view menu.\"/>\n",
    "</div>\n",
    "\n",
    "**3. Select the grading task type for each cell provided in the assignment**\n",
    "\n",
    "\n",
    "Choose one of the following options for each cell while making use of the code/markdown/heading cell options: \n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-3.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of an assignment notebook, with the dropdown created for each cell in create assignment mode.\"/>\n",
    "</div>\n",
    "\n",
    "_**Manually Graded Answer Cells**_\n",
    "\n",
    "Contains an answer that must be manually graded by a human grader.\n",
    "Commonly used for written free-response answers.\n",
    "Typically edited by the student.\n",
    "\n",
    "_**Manually Graded Task Cells**_\n",
    "\n",
    "Contains the description of a task that students have to perform.\n",
    "Must be manually graded by a human grader.\n",
    "Not edited by the student.\n",
    "Asks students to perform a task using multiple cells.\n",
    "\n",
    "_**Autograded Answer Cells**_\n",
    "\n",
    "Contains an answer that will be autograded by the nbgrader extension.\n",
    "Solutions can be specified inline using the special syntax \n",
    "\n",
    "<code>### BEGIN SOLUTION</code>\n",
    "\n",
    "<code>### END SOLUTION</code>\n",
    "\n",
    "During autograding, the solution region will be replaced with a code stub.\n",
    "\n",
    "If the tests pass, the student gets full credit; if the tests fail, the student gets no credit.\n",
    "\n",
    "Autograded answers are not worth any points; points are assigned based on the tests that grade those answers.\n",
    "\n",
    "_**Autograder Tests Cells**_\n",
    "\n",
    "Contains tests to be run during autograding.\n",
    "\n",
    "Tests should <code>assert</code> statements or similar.\n",
    "\n",
    "If the tests pass during autograding, students receive the specified number of points; otherwise, they get zero points.\n",
    "\n",
    "Tests can be hidden using special syntax:\n",
    "\n",
    "<code>### BEGIN HIDDEN TESTS</code>\n",
    "\n",
    "<code>### END HIDDEN TESTS</code>\n",
    "    \n",
    "Hidden tests are removed in the release version.\n",
    "\n",
    "_**Read-Only Cells**_\n",
    "\n",
    "These are marked as cells that cannot be modified by students.\n",
    "\n",
    "They are indicated by a lock icon on the left side of the cell toolbar.\n",
    "\n",
    "The read-only functionality reverses any changes made by the student.\n",
    "\n",
    "#### 4. Example of a NBGrader Assignment\n",
    "\n",
    "The following notebook can be found under this instance's \"JupyterHub_nbgrader\" assignment, and is called \"first_assignment_01.ipynb\" You can also find this notebook in the examples folder of this lesson plan.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-4.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of an assignment showing the various cell blocks available in an assignment.\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a4094b2",
   "metadata": {},
   "source": [
    "### 3.2 Validating an Assignment\n",
    "\n",
    "Once your draft assignment is ready, the next step is to validate. The validation process ensures that the instructor's solutions are accurate and functional, allowing students to pass the assigned tests.\n",
    "\n",
    "**1. Validation Extension**\n",
    "\n",
    "Locate and press the \"validate\" button at the top of the assignment.\n",
    "\n",
    "One of the follow messages will occur:\n",
    "\n",
    "_**Success Confirmation**_\n",
    "\n",
    "If the assignment passes all the tests, a success pop-up message will be displayed, indicating that the solutions are correct.\n",
    "\n",
    "_**Failure Feedback**_\n",
    "\n",
    "If any cells in the assignment fail the tests, a message will be shown specifying which cells have failed and highlighting potential issues that need to be addressed.\n",
    "\n",
    "\n",
    "**Note:** Use “manually graded task” on markdown cells only. Nbgrader doesn’t support its use with code cells. Although you will have an option to select it, it fails in the validation stage.\n",
    "\n",
    "\n",
    "**2. Continue making additional assignments**\n",
    "\n",
    "Add more assignment notebooks or slides to the same folder.\n",
    "\n",
    "**3. Make assignments available to students**\n",
    "\n",
    "To make this folder accessible for the students, the next step is to generate the assignment on the formgrader page. You'll see the small \"generate\" icon in the fifth column to the right (after the \"Edit\" column). Click it.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-6.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the formgrader dashboard, with a red circle showing the small generate icon to make an assignment go live.\"/>\n",
    "</div>\n",
    "\n",
    "You have the option to preview the student’s version of the assignment before release.\n",
    "\n",
    "Once you release it, the assignment gets created in the release folder and students will be able to access it and begin work on it.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47cd56c4",
   "metadata": {},
   "source": [
    "### 3.3 Previewing a Student's View of an Assignment\n",
    "\n",
    "In addition to validating a new assignment, an instructor can preview what a student will see by clicking on the bar-plot icon at the top menu.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-12.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the assignment notebook with an arrow pointing to the bar plot icon that is used to move into a preview mode.\"/>\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "43289896",
   "metadata": {},
   "source": [
    "### 3.4 Student View of Accessing an Assignment\n",
    "\n",
    "The student will see the assignment on the list of main tabs on the root of their homepage.\n",
    "\n",
    "\n",
    "Selecting the assignments tab will list all the (past and present) assignments of the course. A \"Fetch\" button to the right is available for any assignments not yet downloaded:\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-8.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the student's assignment list, with the fetch button highlighted and which the student will select.\"/>\n",
    "</div>\n",
    "\n",
    "Students can press “fetch” to receive a copy of newly posted assignments and start working on them. The assignment will now appear in the \"Downloaded assignments\" section. Clicking on the link to the assignment opens it up as a separate notebook and the student can now start work on it.\n",
    "\n",
    "Once the student completes the assignment, they should close the notebook and return to the assignments page. The student can first validate, then submit.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-9.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the assignments dashboard for students, highlighting the validate option.\"/>\n",
    "</div>\n",
    "\n",
    "The student can access feedback on the assignment by selecting the \"Fetch Feedback\" button:\n",
    "\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-10.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the assignments dashboard for students, with the fetch feedback button identified.\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36f13c8a",
   "metadata": {},
   "source": [
    "### 3.5 Grading an Assignment and Providing Feedback\n",
    "\n",
    "Once the students submit their assignments, the instructor can collect them from the formgrader page, open the submissions and select the autograde button. The grader performs the autograde tasks.\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/nbgrader-11.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of the dashboard containing a list of submissions of assignments, and the small icon selected to trigger an autograde of the assignment.\"/>\n",
    "</div>\n",
    "\n",
    "Instructors can grade the manually graded tasks by clicking on the manual grading tab and following through to apply grades. Instructors can autograde by clicking on the small autograde icon in the autograde column.\n",
    "\n",
    "Finally, instructors can generate and release feedback from the formgrader page.\n",
    "\n",
    "As stated above, students can access that feedback from the assignments tab.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0367d408",
   "metadata": {},
   "source": [
    "### >> Try it out <<\n",
    "\n",
    "Click on the formgrader tab, select \"+ add assignment,\" and practice building an assignment. Try out various cell types and try validating the final assignment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53ab83fb",
   "metadata": {},
   "source": [
    "## 4.0 Building Lesson Plans and Teaching Materials\n",
    "\n",
    "### 4.1 Build Dynamic Lesson-Plan Notebooks\n",
    "\n",
    "Aside from assignmments and exams, you can use notebooks themselves as lesson content for use in and out of class sessions. Notebooks are foundationally an interactive tool. You can add descriptions, links, comments, Latex equations and visualization. You can use these as lecture material and have students work along on their own copies of the shared notebook.\n",
    "\n",
    "Examples:\n",
    "\n",
    " - From Data Services at NYU, a [lesson using a combination of bash and Python cells](https://github.com/NYU-DataServices/RDM_tesseract_ocr/blob/main/Tesseract-OCR.ipynb) to show how a command-line utility works. \n",
    "\n",
    " - A lesson on probability that integrates text, image, and example code that can be adjusted.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9043f3d4",
   "metadata": {},
   "source": [
    "### 4.2 Creating Slides Using RISE\n",
    "\n",
    "JupyterHub is pre-installed with the RISE package, which makes slideshow presentations that can be run on interactive Jupyter Notebooks and easily distributed with nbgrader.\n",
    "\n",
    "Unlike typical slide packages (such as Google Slides), a slideshow created in RISE has native code display plus the ability to run code blocks within the slideshow.\n",
    "\n",
    "Steps to create slides using RISE:\n",
    "\n",
    "**1. Create and name a new notebook on JupyterHub**\n",
    "\n",
    "**2. Edit the notebook with RISE by switching to slideshow mode**\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/rise-1.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of a notebook with slideshow selected under the view menu, thereby turning the notebook into a slideshow.\"/>\n",
    "</div>\n",
    "\n",
    "**3. For each cell, select one of the following content types:**\n",
    "\n",
    "_**Slides**_\n",
    "\n",
    "Use this to move through slides from left to right\n",
    "\n",
    "_**Sub-Slide**_\n",
    "\n",
    "Add a slide below the previous one\n",
    "\n",
    "\n",
    "_**Fragment**_\n",
    "\n",
    "Add a fragment to the previous slide (this gives a slight animation effect)\n",
    "\n",
    "_**Skip**_\n",
    "\n",
    "Use to avoid creating a slide from a cell\n",
    "\n",
    "_**Note**_\n",
    "\n",
    "Use to create a note, no slide is created from the cell\n",
    "\n",
    "<br>\n",
    "<div>\n",
    "<img src=\"img/rise-2.png\" width=\"100%\" style=\"padding: 30px\" alt=\"A screenshot of showing the dropdown menu for each cell that is available in slideshow mode.\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ca9b0c9",
   "metadata": {},
   "source": [
    "**4. Enhance your slides with embedded images and audio**\n",
    "\n",
    "Instructors can embed images and audio to make the slides more interesting. Here are some examples:\n",
    "\n",
    " - https://saturncloud.io/blog/how-to-embed-images-in-jupyter-notebook \n",
    " - https://gist.github.com/tamsanh/a658c1b29b8cba7d782a8b3aed685a24\n",
    "\n",
    "**5. Validate and view**\n",
    "\n",
    "Once you have created your slides, validate and view in slide show mode using the \"validate\" and then the bar graph symbol next to validate on the top of the notebook's page.\n",
    "\n",
    "**6. Presenting a RISE slideshow**\n",
    "\n",
    "In the slide mode, use the following controls:\n",
    "\n",
    "Slide to next slide: next arrow\n",
    "\n",
    "Slide to sub-slide: down arrow\n",
    "\n",
    "Fragment (gets added to slide/subslide): down arrow\n",
    "\n",
    "**7. Sharing a RISE slideshow**\n",
    "\n",
    "Notebooks/slides can be shared with students through various ways. Making use of shared directories is recommended in case of large files, or you could post the slide notebook in the form of material for a chapter along with assignments in the same folder. For examples of what interactive lessons can look like with notebooks using RISE, check out a few examples {{}}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f81d581b",
   "metadata": {},
   "source": [
    "## 5.0 Advanced Integrations\n",
    "\n",
    "### 5.1 Synchronizing JupyterHub with Repositories on Git\n",
    "\n",
    "Follow instructions on the Settings website under Settings>>>Github Repositories, to connect your Github Repo to JupyterHub’s Class Materials folder.\n",
    "\n",
    "Instruct students to save all work within the Class materials folder, which will be backed up to github, depending on the mode you chose in the settings.\n",
    "\n",
    "\n",
    "Caution: When specifying, do note that the default branch on github is now main. So if you're specifying master, ensure that it exists on your branch. Otherwise set it as main (or whatever your branch is)\n",
    "\n",
    "\n",
    "**More Information**\n",
    "\n",
    "Use the links below for more information about nbgitpuller: \n",
    "\n",
    " - https://nbgitpuller.readthedocs.io/en/latest/\n",
    " - https://docs.qubole.com/en/latest/user-guide/notebooks-and-dashboards/notebooks/jupyter-notebooks/managing-jupy-notebook-versions/link-jupy-notebook-github.html\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72aebd56",
   "metadata": {},
   "source": [
    "### 5.2  Working with MySQL Databases on JupyterHub\n",
    "\n",
    "It is possible to create a MySQL database and use it for teaching a class from JupyterHub. This makes it easy to integrate databases with JupyterHub server while adding a layer of security by not enabling access to the database if the client is not from JupyterHub.\n",
    "\n",
    "Once the database is created, it is recommended to create various user types and set their access permissions, typically, one for instructors with grant all access privileges and one for students with read-only permissions. This may vary based on the use-case. \n",
    "\n",
    "Steps for creating a database and users with different access levels:\n",
    "\n",
    "**1. Select Create MySQL DB from Setting => MySQL on the settings page**\n",
    "\n",
    "**2. Create various user types and set their access permissions**\n",
    "\n",
    "Once the database is created, it is recommended to create various user types and set their access permissions. \n",
    "\n",
    "Typically, one for instructors with grant all access privileges and one for students with read-only permissions, but this may vary based on the use-case. \n",
    "\n",
    "Create a new environment:\n",
    "\n",
    "<code>conda create \\{{environment name\\}}</code>\n",
    "    \n",
    "To activate the conda environment, use:\n",
    "\n",
    "<code>conda activate \\{{environment name\\}}</code>\n",
    "\n",
    "To install mysql package if not installed already:\n",
    "\n",
    "<code>conda install mysql</code> \n",
    "\n",
    "To connect to the created MySQL server with command options:\n",
    "\n",
    "<code>mysql --host=mysql-tutorials-1.db --user=root --password= {{PASSWORD}} mysqldb</code>\n",
    "\n",
    "The password will be located on the settings page next to Create MySQL DB icon\n",
    "\n",
    "Once the connection is established, sql statements can be followed to create a user and set the permissions:\n",
    "\n",
    "<code>CREATE USER 'instructor'@'%' IDENTIFIED WITH mysql_native_password BY ‘{{instructor password}}’;</code> \n",
    "    \n",
    "<code>GRANT ALL ON mysqldb.* TO `instructor`@`%`;</code>\n",
    "\n",
    "<code>CREATE USER 'dbreader'@'%' IDENTIFIED WITH mysql_native_password  BY ‘{{student password}}’;</code>\n",
    "\n",
    "<code>GRANT SELECT, SHOW VIEW ON `mysqldb`.* TO `dbreader`@`%`;</code>\n",
    "\n",
    "Once this is setup, the mysql package can be used to make connections and execute queries using the notebooks. \n",
    "\n",
    "Operations like create/alter schema, add/delete/select records can be performed based on the permissions the user has. \n",
    "\n",
    "Refer to mysql_sample in the shared folder for a sample code on creating table schema and adding records to the table.\n",
    "\n",
    "### More Information\n",
    "For more information about the mysql package and ways to use it: https://www.w3schools.com/python/python_mysql_getstarted.asp\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e709a19",
   "metadata": {},
   "source": [
    "## 6.0 Important Considerations\n",
    "\n",
    "**Resource Allocations for Exams**\n",
    "\n",
    "When instructors use this platform for organizing a test, the whole cohort of students may have to login at the sametime.\n",
    "\n",
    "However, GCP needs time to allocate resources. For this purpose, instructors should pre-allocate resources by adding \"placeholders.\" Each placeholder allocates 500 MB for 1.5 hours. For a regular script writing/debugging, etc., 500 MB is sufficient, so typically, add one placeholders per student taking the exam one hour before the assessment to ensure resources are available.\n",
    "\n",
    "The placeholder settings are found in the main dashboard under Settings >> Extra Placeholders"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7d125bcf",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}