We hope you are enjoying Jupyter Hub. This is a pilot project, supported by Brown Computing Information Services (CIS). We are a small team at the moment and therefore support is somewhat limited. We have created few mediums for you to see assitance.

• Please check the FAQ section in this book

• For general usage questions, we encourage you to take advantage of the CCV's Disscussion Forum and CCV's Community Slack

• If you are experiencing technical issues, for instance, the Hub appears to be down or you have access issues, you can email jupyter-help@brown.edu

Why can't I sign into the JupyterHub?

There are two main reasons why you are unable to log into JupyterHub.

First, you may not have been approved to use the hub. If you are not actively enrolled in a class at Brown which is utilizing this service, then you will not have access to the Hub. Furthermore, if you previously had access and the class has since ended, permissions to the Hub are revoked at the end of semester.

Second, you may be trying to login with an unauthorized email address (not a @brown.edu login email). Please ensure you are using your Brown email address, and that you permitted to access the Hub.

My server is taking a long time to start or not starting! What do I do?

Resources on the Hub may be experiencing heavy load at the moment. We implement an auto-scaling of Hub resources when we detect the system is reaching capacity. If your server is taking a few moments to start, it is likely that the system is currently scaling up more resources, and this should only take a few minutes.

My server just says "Your server is stopping". What do I do?

This means that your server has been halted and is rebooting. This may be because you were inactive for an extended period of time. If you experience this message, please wait a few moments and try to login again.

My notebooks are running really slow. What is wrong?

You may have several active notebooks running in the background which could be consuming resources. It is recommended you close any unused notebooks as seen in the instructions Managing Active Notebooks

If the notebook continues to run slow, we recommend you restart the notebooks kernel as seen in the Managing Active Notebooks.

My notebook is completely frozen! How can I restart it?

First try restarting the notebook kernel as seen in the Managing Active Notebooks. If the issue persists, restart your server by following the instructions in Shutting Down Server.

I keep getting a "File Save Error" or "Insufficient Permissions". What is wrong?

This error happens when you are launching a notebook file from Google Drive which you do not have write permissions to. If you are using a notebook shared through Google Drive which you are not permitted to write to, please first copy the file to your personal Drive by right clicking on the file and selecting "Add to my Drive".

Can I create notebooks directly on the hub without using Google Drive?

Yes, you can created files and run notebooks on the hub disk space, but they are not backed up. This means that if hub shuts down (for rolling restarts, system failures, etc), all the local data will be lost. We advice you use this at own risk as it is not an intended workspace for long-term notebooks.

Can I collaborate with other users on a notebook at the same time?

Currently, the collaborate feature for notebooks has been disabled due to developmental reasons. You can share notebooks with other users the same way you would share any file on Google Drive, but they cannot be actively worked on by multiple users simultaneously.

I have my own notebooks. How can I run them on the hub?

Yes you can, but please remember that the Brown JupyterHub is for academic purposes only. You can use the upload feature within the JupyterHub, or simply upload it to your google drive externally and launch it from within the Hub.

Can I use a different programming language such as python 2.x or Julia?

The kernels supported are tailored to each class. Some environments have multiple supported kernels, while others only support Python 3

I can’t find my notebook I was working on last session.

Ensure you are looking in the right drive folder where you saved it. Please follow the steps provided in the Launch an Existing Notebook.

I am having an issue not discussed here. How can I get help?

Please feel free to contact us at jupyter-help@brown.edu with any questions/comments/concerns regarding anything JupyterHub.

What is the Jupyter Notebook (provided by official documentation)

Introduction

The Jupyter Notebook is an interactive computing environment that enables users to author notebook documents that include:

• Live code

• Interactive widgets

• Plots

• Narrative text

• Equations

• Images

• Video

These documents provide a complete and self-contained record of a computation that can be converted to various formats and shared with others using email, Dropbox, version control systems (like git/GitHub) or nbviewer.jupyter.org.

Components

The Jupyter Notebook combines three components:

• The notebook web application: An interactive web application for writing and running code interactively and authoring notebook documents.

• Kernels: Separate processes started by the notebook web application that runs users' code in a given language and returns output back to the notebook web application. The kernel also handles things like computations for interactive widgets, tab completion and introspection.

• Notebook documents: Self-contained documents that contain a representation of all content visible in the notebook web application, including inputs and outputs of the computations, narrative text, equations, images, and rich media representations of objects. Each notebook document has its own kernel.

Notebook web application

The notebook web application enables users to:

• Edit code in the browser, with automatic syntax highlighting, indentation, and tab completion/introspection.

• Run code from the browser, with the results of computations attached to the code which generated them.

• See the results of computations with rich media representations, such as HTML, LaTeX, PNG, SVG, PDF, etc.

• Create and use interactive JavaScript widgets, which bind interactive user interface controls and visualizations to reactive kernel side computations.

• Author narrative text using the Markdown markup language.

• Include mathematical equations using LaTeX syntax in Markdown, which are rendered in-browser by MathJax.

Kernels

Through Jupyter's kernel and messaging architecture, the Notebook allows code to be run in a range of different programming languages. For each notebook document that a user opens, the web application starts a kernel that runs the code for that notebook. Each kernel is capable of running code in a single programming language and there are kernels available in the following languages:

• Python(https://github.com/ipython/ipython)

• Julia (https://github.com/JuliaLang/IJulia.jl)

• R (https://github.com/IRkernel/IRkernel)

• Ruby (https://github.com/minrk/iruby)

• Haskell (https://github.com/gibiansky/IHaskell)

• Scala (https://github.com/Bridgewater/scala-notebook)

• node.js (https://gist.github.com/Carreau/4279371)

• Go (https://github.com/takluyver/igo)

The default kernel runs Python code. The notebook provides a simple way for users to pick which of these kernels is used for a given notebook.

Each of these kernels communicate with the notebook web application and web browser using a JSON over ZeroMQ/WebSockets message protocol that is described here. Most users don't need to know about these details, but it helps to understand that "kernels run code."

Notebook documents

Notebook documents contain the inputs and outputs of an interactive session as well as narrative text that accompanies the code but is not meant for execution. Rich output generated by running code, including HTML, images, video, and plots, is embedded in the notebook, which makes it a complete and self-contained record of a computation.

When you run the notebook web application on your computer, notebook documents are just files on your local filesystem with a .ipynb extension. This allows you to use familiar workflows for organizing your notebooks into folders and sharing them with others.

Notebooks consist of a linear sequence of cells. There are four basic cell types:

• Code cells: Input and output of live code that is run in the kernel

• Markdown cells: Narrative text with embedded LaTeX equations

• Heading cells: 6 levels of hierarchical organization and formatting

• Raw cells: Unformatted text that is included, without modification, when notebooks are converted to different formats using nbconvert

Internally, notebook documents are JSON data with binary values base64 encoded. This allows them to be read and manipulated programmatically by any programming language. Because JSON is a text format, notebook documents are version control friendly.

Notebooks can be exported to different static formats including HTML, reStructeredText, LaTeX, PDF, and slide shows (reveal.js) using Jupyter's nbconvert utility.

Furthermore, any notebook document available from a public URL on or GitHub can be shared via nbviewer. This service loads the notebook document from the URL and renders it as a static web page. The resulting web page may thus be shared with others without their needing to install the Jupyter Notebook.

Welcome to the Brown University JupyterHub Documentation & Quickstart Guide. The Brown JupyterHub is designed to provide an environment to run Jupyter Notebooks for Python, Julia, R, and other languages without the need to install any software or packages. JupyterHub is interacted with completely through a web browser. This service is a collaboration supported by various teams in CIS.

If you are an instructor looking to request a JupyterHub for your course or workshop, please visit this link.

How To Use This Guide

This document is designed to help instructors and students use their JupyterHub. This guide also provides extensive documentation on different workflows used to distribute materials to the hub. Depending on a specific workflow, there are different sections of this documentation that are more relevant to you. To help you identified those sections, we make use of the following labels depending on your role and workflow

1. Determine your workflow

2. Use labels as a guide to revelant sections ① Basic usage guide ② Advanced usage guide Ⓣ Teacher guide - Ⓢ Student guide

What Do You Get?

On the Brown JupyterHub, each user is provided their own persistent working directory and compute resource allocation unique from each other user. This means the environment you are provided is only accessible by yourself and CIS support staff.

Once connected to your server, you are provided an isolated workspace where you can write and run code. There are no time limit restrictions or specified lockout times, so please feel free to use your personal JupyterHub notebook server anytime you want and adhere to CCV's Computing Policies

At times, the current release of JupyterHub/JupyterLab may have know issues. We list the here for you to be aware

Close your JupyterHub tabs!

Brown JupyterHub Terms and Service Agreement

GENERAL TERMS AND CONDITIONS

All use of Center facilities and services is at the discretion of the Center Director.

All use of Center facilities must conform to established University policies as published in documents held at [https://it.brown.edu/computing-policies].

Accounts on Center equipment are to be used only by the named individual holder of the account. Users may not share passwords or accounts with anyone. Misuse or unauthorized access is prohibited, and is subject to University sanction and/or criminal and civil penalties. The Center's support staff may, in the course of providing support to a user, access the Center's systems and the user's files through that user's account. Before doing so, permission will be required from the user either in person or in writing.

All software and data stored or used on Center and hosted systems must be appropriately and legally acquired and must be used in compliance with applicable licensing terms. Unauthorized misuse or copying of copyrighted materials is prohibited. The storage of any sensitive data must comply with all appropriate laws or protocols, such as those imposed by Protection of Human Subjects procedures, and the Center should be notified of the location of such data.

In addition, users certify compliance with all U.S. export control laws and regulations and are responsible for obtaining export control licenses as may be required before exporting controlled data, information software, or other technology to foreign countries or providing access to foreign persons.

Papers and publications resulting from use of Center facilities must acknowledge this via the inclusion of an appropriate credit similar to the following: "This work was supported by Brown University through the use of the facilities of its Computing and Information Services."

Interruptions in Center resource operations and services may be due to planned maintenance or other, unforeseen cause. Users will be notified whether or not maintenance will occur and what systems will be affected at least one week in advance of the maintenance period.

Emergency system changes may also be necessary to correct hardware or software failures, or to patch security vulnerabilities in systems software. Such changes will be announced with the longest notice possible.

Computing Policies

The following documents are official policies of Brown University that are related to computing issues. They have been adopted to ensure an equitable, appropriate, and legal use of Brown resources. You are therefore responsible for having reviewed the listed policies and for complying with their requirements. Violation of a computing-related policy may result in disciplinary action, up to and including suspension or termination.

In order for policies to be officially approved and published as final, they must go through a formal policy review process. Should the need arise to have a policy published before the process is complete, the document will be published as an interim policy while the process is completed.

Depending on how familiar students are to Version Control technologies such as Git, different workflows may fit best the strategy used to distribute coding materials and assignments.

Ⓢ① Students in classes that are new to programming and/or version control

Related sections in the documentation (look for ① and Ⓢ in the section title):

• Getting Started

• Using Your Hub

• Getting Support

Ⓣ① Teachers looking for a simple way to distribute materials to students who will NOT be introduced to git.

There are two options:

Direct Upload:

This simple workflow assumes no git knowledge from the student nor the instructor. Notebook files are shared via CANVAS and directly uploaded to JupyterHub

Related sections in the documentation (look for Ⓣ ① in the section title):

• Getting Started

• Using Your Hub

Via Smart Link

Using this workflow, teachers have the ability to generate a smart link that pulls the materials automatically for students into their JupyterHub. If you are a teacher using this method, you will need basic familiarity with git and github.

Related sections in the documentation :

• Content sync via link Ⓣ①

ⓉⓈ② Teachers and Students using Git/GitHub and GitHub Classroom

Using Git and GitHub to distribute your materials encourages best practices for software development and additionally adds versioning to changes made to the source code, allowing students to revert to prior versions if necessary. If you will be using Git, we recommend using GitHub Classroom to help automate the process.

Related sections in the documentation (look for ② in the section title):

Ⓢ Students should familiarize themselves with:

• Content Sync via GIT

• GitHub Classroom (Student Guide)

Ⓣ Teachers should familiarize themselves with:

• Content Sync via GIT

• GitHub Classroom (Instructor Guide)

• Share https://docs.ccv.brown.edu/jupyterhub/ with all students.

• If planning to use hub during class time, have the students launch their hubs at the very beginning of class (can experience a few minutes of bootup time if large spike active hubs)

• Familiarize yourself with the Admin Tab. You can access by visitin File -> Hub Control or by visiting https://<yourclassid>.jupyter.brown.edu/hub/admin. Through this interface you can stop and restart their server if they are having troble accessing their environment.

• Make sure to add your TAs a an Admin Users. You can do so by editing their user in the Admin panel above.

• Is a required package missing? Hub crashing? Need more computational resources? Student having an issue you cannot resolve? Don't hesitate to email us at jupyter-help@brown.edu

If you are using Git and GitHub Classroom

• Create and share your GitHub classroom invite link with students

• Remind students to push to their github repo at the end of every session (or whenever they make major progress on a project). Instructions are in JupyterHub guide above.

Sample instructions for students: Thanks Andras Zsom for sharing:

DATA1030 Instructions for GitHub Classroom Assignments

JupyterHub provides a way to serve Jupyter Notebooks for multiple users. At Brown, we typically deploy JupyterHub in Google Cloud. The figure below depitcs the concept and technology behid JupyterHub.

If you wish to learn more about JupyterHub, you can visit the project's documentation

Opening an Existing Notebook on Your Hub

To launch a Jupyter Notebook (.ipynb) file on your hub, you can simply double click on it to launch a kernel session with that notebook.

1. Select File browser from left sidebar

2. Locate the notebook you wish to open using the file browser

3. Double click or right click on the file and select Open

4. A new tab will launch containing your Notebook

Depending on your class requirements and on your level of familiarity with version control, there are different recommended ways to sync files to and from your hub. We list several options below.

Adding Files From Your Desktop ①

The File Uploaded tool offers the easiest approach for students to add files to your hub.

1. Select File browser from left sidebar

2. Select the Upload Files button

3. Select the files you would like to upload and click Open

4. The files will be automatically added to your hub at your current working directory level.

Import via URL ①

Ⓣ Teachers have the ability to generate an URL that will place the appropriate content in your hub. If you are an Instructor, please refer to the Link Generation Section.

Ⓢ Students will simply need to clink the link posted in Canvas. Note that if the content is updated by the instructor, then visiting the link again will bring the new content.

Import from Git/GitHub Repository ②

Many courses at Brown use GitHub and GitHub classroom to distribute lecture and homework material. If your class uses GitHub and GitHub classroom for content distribution, you should review the sections CONTENT SYNC VIA GIT, and GITHUB CLASSROOM from the left navigation bar.

Terminal sessions provide text-based/command-line access and interaction with the operating system. In an environment such as JupyterHub, users have a limited ability to graphically interact with the underlying operating system. The terminal session gives users the ability to work directly with the filesystem via a Unix-like shell. This is a very useful tool, and one that has applications for anyone working in any field related to technology. Therefore, it is often useful and necessary to have interactions via a terminal session.

Launch a terminal on JupyterHub

1. Select the localFile Browser from left sidebar

2. Create a new launcher using the New Launcher button

3. Click the Terminal icon under the Other section

4. A new “Terminal #” window will appear your browser with a prompt similar to jovyan@jupyter-first-5flast:~$

Creating a Notebook on JupyterHub

To create a notebook on JupyterHub, follow the instructions below:

1. Select the localFile Browser from left sidebar

2. Create a new launcher using the New Launcher button

3. Click Python 3 under the Notebook section

4. A new “Unititled(#).ipynb” file will appear in your current working drive directory and a blank Notebook will launch. Click on "Untitled" to change the name of the file

Introduction to Python Notebooks

For new users of Python3, we have provided access to an introduction to Python3 notebook series. This can be added to your local JupyterHub drive by clicking on the following link: .

This link will automatically download the course content into you hub and then launch an instance. To run the provided exercises, follow the instructions below:

1. Click on . Wait for the download process to finish.

2. Select the localFile Browser from left sidebar

3. Click on the Home icon above your Browser region.

4. Navigate into learn-python3.git/notebooks

5. Select from the beginner or intermediate notebook lessons

6. Double click or right click > Open the desired notebook lesson.

Further Reading

Python3 Official Documentation:

Jupyter Notebook Official Documentation:

Jupyter Lab Official Documentation:

is a tool lets you distribute content in a git repository to your students by having them click a simple link. It relies on that ensures that your students are never exposed to git directly. This tools comes pre-installed in your JupyterHub.

If you are not familiar with git and GitHub, we recommend you visit the section of this documentation. Before you can start using nbgitpuller you will need a GitHub account and a repository that you wish to distribute to your students.

Once you have a repository with the material that you wish to distribute, you can generate an nbgitpuller links with the . The requirements of the generator are depicted and explained below. The circled locations required special attention

1. This is the link generated. It can be copied and sent to your students

2. The url of your hub

3. The git repository where you have published your content. Please notice that the url can start either with git:// or https://. If you are not expencting your students to have configured github authentication/ssh keys nor have a GitHub account, make sure you use https://.

4. Notice that your URL does not end in .git. (This is often the case if you are pasting URL from GitHub)

5. The branch of the repository you wish to distribute

6. Optionally, a particular file or directory you want to automatically open for your students once the repository has been synchronized.

7. Choose the JupyterLab interaface as this is the default for all of Brown's Hubs

8. Select the Default version of the link, even if distributing the link via Canvas

When to use nbgitpuller

1. You are running a JupyterHub for a class & want an easy way to distribute materials to your students without them having to understand what git is.

2. You have a different out of band method for collecting completed assignments / notebooks from students, since they can not just ‘push it back’ via git.

When to NOT use nbgitpuller

1. You are an instructor using a JupyterHub / running notebooks locally to create materials and push them to a git repository. You should just use git directly, since the assumptions and design of nbgitpuller will surprise you in unexpected ways if you are pushing with git but pulling with nbgitpuller.

2. Your students are performing manual git operations on the git repository cloned as well as using nbgitpuller. Mixing manual git operations + automatic nbgitpuller operations is going to cause surprises on an ongoing basis, and should be avoided.

Shutting Down Notebooks

You can perform standard actions on your notebook files by right clicking on any individual file or directory. This will provide a list of applicable actions via a drop down menu. Options include cut/copy/paste, rename, download, duplicate, delete, and shutdown kernel (stopping the specific notebook processes).

Notebook kernels actively running have a small green circle icon to the left of the filename indicating their status (as seen in the example provided).

Additionally, you can manually manage actively running notebook kernels and terminals by selecting the Running Terminals and Kernels sidebar option. This will provide a detailed list of all active notebooks with the ability to halt their processes by using the Shutdown button

Restarting Notebook Kernel

Periodically a given notebook may begin to misbehave. This can be due to a poorly constructed segment of code, resource overflows, or other similar events. A common solution to these types of problems is to restart the notebook kernel, which will release any memory and variable states of the notebook and reload them. This can be done by selecting Kernel > Restart Kernel.

JupyterLab

JupyterLab is the next generation web-interface for Jupyter Notebooks. It enables you to use side by side view, text editors, terminals, data file viewers, markdown preview and other custom components along with notebooks. Highlighted features are:

• Drag-and-drop to reorder notebook cells and copy them between notebooks.

• Run code blocks interactively from text files (.py, .R, .md, .tex, etc.).

• Link a code console to a notebook kernel to explore code interactively without cluttering up the notebook with temporary scratch work.

• Edit popular file formats with live preview, such as Markdown, JSON, CSV, Vega, VegaLite, and more.

To learn more, please see the official documentation at

Brief JupyterHub Lab Interface

1. File: actions related to files and directories

2. Edit: actions related to editing documents and other activities

3. View: actions that alter the appearance of JupyterLab

4. Run: actions for running code in different activities such as notebooks and code consoles

5. Kernel: actions for managing kernels, which are separate processes for running code

6. Hub: actions related to the hub such as shutdown or logout.

7. Tabs: a list of the open documents and activities in the dock panel

8. Settings: common settings and an advanced settings editor

9. Help: a list of JupyterLab and kernel help links

10. File Browser: Local file browser for JupyterHub. Not synced with Google Drive

11. Git Plugin Actions: View of files that have changed and an interface to git actions such as stage, commit, push and pull

12. Running Terminals and Kernels: List of active running kernels.

13. Command Palette: Keyboard-driven way to search for and run JupyterLab commands

14. Open Tabs: List of active notebook tabs and related functionality

15. Browser Window: Active browser window.

16. Git Clone: Add or clone a new repository

17. Notebook launcher: Available notebook kernels to launch.

18. Terminal launcher: Launch a new terminal window

Before Getting Started

Prior to accessing Brown’s JupyterHub, you will need the following:

• A supported web browser (Chrome, Firefox, Safari, Microsoft Edge)

• Be enrolled in a course at Brown that utilizes JupyterHub (ask your professor)

• Have read through the

Sign In

Start using JupyterHub by signing in to your account for your class.

1. Go to and click "Sign in with Brown Gmail Login" NOTE: (replace [department] with your corresponding course department, ie: phys for Physics 70 or Physics 1400 etc.

2. Enter your Brown email address (example: john_doe@brown.edu) and password

Once authenticated, you should automatically be logged in and a JupyterHub server will begin launching. A status bar will appear with detailed information regarding your server startup.

Git is a version control system that enables you to track changes to files. With Git, you are able to revert files back to previous versions, restore deleted files, remove added files and even track down where a particular line of code was introduced.

Git creates a hidden .git folder (in the current folder) to store the details of the file system - this folder contains all the data required to track your files and is known as a repository, or repo.

Git tracks file changes by the user creating a save point, or in Git terms a commit. Each commit takes a snapshot of the current file system. Commits are uniquely identified by a SHA–1 hash. This is a 40 character string which may along the lines of ded7a0db6422d59e9893e975e32275fc36f853daThis hash can be used to track a particular commit within the repository.

Nearly all operations that are performed by Git are in you local computing environment, for the exception of few used purly to synchronize with a remote. Some of the most common git operations are depicted below. In summary a typical flow consists of making changes to your files, staging them via git add, marking a save point via git commit, then finally syncing to your remote (e.g., GitHub) via git push. If you are pushing changes to your remote from multiple places, you can bring changes your most recent version usin git pull, which is the equivalent of doing git fetch followed by a git merge operation

Shutting Down Your Server

Once you are done working, we recommend you manually close down your JupyterHub server by using the JupyterHub Control Panel. This will ensure your session is safely shutdown and the resources you were using are released back to the hub.

1. File > Hub Control Panel

2. Click Stop My Server.

This method is highly recommended as it stores the state of the machine prior to booting down. This means that the next time you connect to your server, any notebooks running will be automatically resumed.

Alternatively, if your server is timed out due to inactivity (ie: simply walking away from your live server), we cannot guarantee automatic notebook booting upon your next login.

Once you have made changes to an assignment and are ready to save your progress, there are a few steps that you must do prior to closing the hub if using git to keep your changes save. Once again, the interaction with git can be via Plugin user interface or a terminal session

1. Saving your work using GIT Plugin (UI)

Saving your changes and uploading them to GitHub is outlined and illustrated below:

1. Select the Git Plugin tab from the left sidebar

2. Files that have chaged will show under the Changed category. New files will appear under the Untracked category. Use to move your changes to the staging area () and use the to unstage.

3. Once all files have been staged, you can commit your changes by typing a commit message

4. Confirm your commit

5. Finally, you need to push your commited changes to GitHub. You do so using the icon

2. Saving your work using GIT command line

2.1: Open terminal and move to working assignment directory

1. Launch a terminal on JupyterHub

2. Navigate to your current working assignment directory using the cd command

2.2: Commit Changes to be Saved (git add/commit)

From the directory containing your actively worked on assignment, you must first add and commit changes you have made which will be prepared to be saved remotely on the git repository. Think of this as staging any changes you have made, but not actually saving them yet. This first step provides the opportunity to add a commit message where you can document the changes you have made with this current save, which should be descriptive but not necessarily comprehensive.

2.3 Save Changes to Repository (git push)

It will require you to enter your github credentials and then will begin to save the changes to your remote repository for the git classroom.

Step 0: Create a GitHub Account (if you don't have one)

In order to use github and github classroom, you must first create a github account (if you already have an existing account, you can skip this step). To create an account, go to and complete the account creation process. We recommend you use an username that will easily allow your professor or students to identify you.

Basics Git Commands

For the complete Git cheatsheet (provided by GitHub) go to the link below or go to

Additional Resources:

Learn Git interactively:

GitHub

Atlassian Git Tutorial

What Is GitHub Classroom?

GitHub Classroom is a way to distribute coding homework assignments though the use of Git, a powerful tool for version control and remote storage of programming projects. For your work on Brown's JupyterHub, GitHub is the recommended method for saving and storing your active projects as it is not only the industry standard, but it you can take your projects with you as the foundation of your programming portfolio.

GitHub Classroom operates on a classroom organization level, where students are invited to join classrooms hosted by instructors. Once part of a GitHub classroom, assignments will be distributed and you will be given your own personal clone of the assignment, where you are free to make changes and save the product which is automatically synced and shared with your instructor. The next steps will help you to get started using GitHub classroom provided your instructor is utilizing this tool for their class.

Step 0: Create a GitHub Account

In order to use github classroom, you must first create a github account (if you already have an existing account, you can skip this step). To create an account, go to and complete the account creation process. We recommend you use an appropriate username is it is publicly visible.

Step 1: Join Your GitHub Classroom

Once you have a GitHub account, you must join your classes corresponding GitHub Classroom organization. To do this, follow the link provided by your instructor's classroom invitation link. This will require you to sign in to your GitHub account, and then you will automatically become linked!

We recommend syncing content to and from JupyterHub using Git and GitHub. However, before you can start, we will need to tell Git and GitHub who we are.

0. Start a Terminal Session Inside of JupyterHub

1. Start a terminal session inside your hub using the terminal launcher (#18 in the )

1. Configure Git

In the terminal in JupyterHub, enter the following commands:

Set your git identity with your name and email

Set default configurations for git. These commands will set git to always clone using SSH and set the default branch name to main rather than the traditionally used master

2. Generate an SSH Key

1. Generate an ssh key:

This creates a new ssh key, using the provided email as a label.

3. When you're prompted to "Enter a file in which to save the key," press Enter accept the default file location.

3. Adding a new SSH to your GitHub Account

1. Copy the SSH public key to your clipboard

The following command shows the public SSH key on the terminal.

Copy the entire key which starts with ssh-rsa and ending with "your_email@example.com"

1. In the "Access" section of the sidebar, click SSH and GPG keys.

2. Click New SSH key or Add SSH key.

3. In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal Mac, you might call this key "Personal MacBook Air".

4. In the "Key type" field it should say Authentication Key

5. In the "Key" field, paste your public key

6. Click Add SSH key

4. Test your ssh connection on JupyterHub

1. In the terminal of your hub type

1. After accepting the host key you should received:

Congratulations! You've successfully authenticated Github in JupyterHub!

5. For more information check GitHub's documentation:

Learning Management system/LMS

Examples: Blackboard, Moodle, Canvas. Google Classroom

Teachers often use a learning management system in keeping with student privacy regulations. Classroom has a lightweight integration with LMS ecosystem--students can submit a link to their repositories.

You can use the RISE Plugin available from the Classic Notebook Interface to turn your Jupyter Notebooks into a slideshow

Brown's JupyterHub uses Jupyter Lab by default. If for some reason you want to access the classic interface replace the lab? part of the url with tree

GitHub Classroom makes it easy to distribute materials and assigments to students while maintaining the ownership in your own organization. The following diagrams will help you understand these workflows. To get started follow guides in the remider of this section.

Why use GitHub Classroom:

• Introduce students to version control, one of the most important and foundational practices in software engineering.

• Automate assigment set up: Share a single link with your students. When they accept, they will have their own copy of the assignment inside your organization

• Configure assignments: Assigments can be configured to be individual or for groups, private or public .

• Download all repositories easily: With GitHub's desktop client, Classroom Assistant.

• Keep you class materia organized year after year: Version control is a good way to keep track of the material and changes that you make from one year to another.

Possible Disadvantages:

• Students and you will need to create an account in github

• Students and you will need to learn a little bit if Version Countrol (git),

• You may need to spend a class on the basics of Git

Each instance of a Jupyter Hub is tailored to the computing needs of each class. All dependencies and libraries are installed in a docker images supported by CCV - see https://github.com/brown-data-science/docker-stacks.

If you are an instructor and need additional packages, libraries or plugins, please contact us.

If you are a student and want to try additional libraries that are not pre-installed in your Hub, you can install them in your own instance but you need to keep few considerations in mind.

• Any location besides HOME is ephemeral. Therefore if you want and installation to persist though sessions you will need to install them in your /home/joyvan

• To achieve persistent installs using pip you can use: pip install --user <package>

• If installation is via Conda the best approach maybe to create a new environment and set the path to be somewhere inside HOME

Installing Julia Packages

To install Julia packages, first activate a project in a new folder or your home.

julia
]activate .

Then, install packages in that Project. That will create a Project.toml and a Manifest.toml in that folder.

For more information, check Julia's Pkg Documentation.

Option 1: Distribute using nbgitpuller

See nbgitpuller page to see how to generate links for distributing your repository

Option 2: Distribute one lecture materials as assigments

1. Have the materials for one lecture in a repository 2. Distribute as assignment, with its own link, and no deadline

Advantages

• Students can stay as outside collaborators for ever.

• There is no special consideration for shopping period

• All of their lecture work is automatically set up in your organization … with a default place for them to work there are less chances for them to be pushing it to their own public GitHub…

• Less management of merging conflicts and remotes

Disadvantages

• There will be a lot of repositories in the organization.

• No simple mechanism for pushing changes after distributiom

Option 3: All lectures in one repository

During shopping period:

1. Set up the lectures to be public

2. Students clone and pull from public repository

After shopping period:

1. Have a first assigment to generate a link. 2. Students that accept the link become outside collaborators in your organization 3. Invite the students to join the organization. 4. You should make a team for the students and give them read access to the private lecture repository 5. As members of the organization, they can create a repository to push their personal changes to the lectures. In order to sync with their own repository and with yours, they will need to set up two remotes. See https://help.github.com/articles/adding-a-remote/ for more help

Step 1: Request an organization for your class

You can follow instructions GitHub's instruction to create your organization. Plese note that you should create a different organization per class per year, for example CS50-spring19. Also will be requesting a free plan and applying for a classroom discount that will allow you to have unlimited private repositories. To request the discount, follow directions here.

Step 2: Create a classroom

Visit https://classroom.github.com/classrooms to create your classroom. You will be asked to select an organization fro your classroom. Follow link to grant access to your newly created organization, after that, you will be able to select it

After selecting your organization, you will be asked to name your classroom, invite admin members and add a class roster. Skip steps to set up your roster for the moment.

Congratulations! You are now ready to start using your classroom to distribute assigments and if desired, your lecture.

Workflow Overview

Distributing Homework

To create assignments, visit your classroom home and select upper right button to create a new assignment

Considerations

• Choose appropriate level of privacy: Private or public

• Give students admin on their repo. That means they could invite other people to it, make it public etc

• Select starter code from a pre-existing repository

Distribute homework link

Grading and Feedback

After the submission deadline, there are several workflows you can follow. Here we outline few suggestions and we invite you to contribute, your own workflows.

Clone all homework repositories (with and automated script - coming soon), then:

Possible ways of generating feedback include:

General Comments:

• README

• CANVAS

Inline comments:

• Write markdown cells inside the hub - commit and push

  • Student views inside jupyterhub

  • Could use https://www.reviewnb.com/ for nicer diff

• Write to a script .py that is kept insync

  • Student views inside github

• PDF feedback via CANVAS

Downloading a GitHub repository into your JupyterHub is done via git clone. The operation can be done via the Git Plugin interface that comes pre-installed in your JupyterHub or a terminal session

Prerequisites :

• 1. GitHub Username, Password and Email. See Create GitHub Account

  2. You have authenticated your JupyterHub and GitHub Accounts. See Configuring Git in JupyterHub

Clone using a terminal session

Launch a terminal on JupyterHub by following the instructions below:

1. Launch a terminal session

2. Clone your assignment to the hub using the git clone command

git clone <gitURL>

To launch a specific notebook file downloaded, see the Launch a Notebook steps

Using the Git Plugin Interface

1. Select the Git Clone button circled in blue below

2. Paste the url at the prompt

3. A new folder with your repository will show in your file browser

To launch a specific notebook file downloaded, see the Launch a Notebook steps

Step 1: Accept Assignment

In order to begin working on your assigned coding project, you must first accept the GitHub assignment by clicking on the corresponding assignment link provided by your instructor. It will require you to log into your GitHub account (if you do not have one, see Getting Started - Create a GitHub account). Once logged in, click the Accept this assignment and your repository will be automatically generated.

Step 2: Copy Assignment URL

Once your assignment repository has been created, you must get the exact URL to the assignment you wish to download to the hub. To do this, either a) click the corresponding link for where your assignment has been created (see image above), or b) navigate to your github repository list, then:

1. Navigate to the assignment you wish to work on in GitHub

Step 3: Download to content to JupyterHub

Follow the steps in the Downloading Content page in the previous section

Step 4: Save and upload changes to your assigment materials

As you work on your assigment, it is a good practice to commit and push your changes regularly. Follow the steps in the Saving and Uploading page in the previous section

If you want to replicate the JupyterHub environment elsewhere. We provide Conda and Julia environment files with the packages installed in the class' image.

The files are available for download from this .

To recreate the Conda environment

1. Download the environment.nb.yml file

2. Create the environemtn using the file.

To recreate Julia enviroments

1. Download the Project.toml file and add it to your project's folder and rename it to Project.toml

2. cd into your folder

3. From the Julia REPL:

For users who want a more powerful text editor, we provide Visual Studio Code. You can launch a VSCode instance from Jupyter Lab.

In addition to using the R kernel in Jupyter Lab or Notebook, you can also take advantage of RStudio. Just use the launcher to open a new session for RStudio. You can also create RShiny apps and use the Shiny launcher to serve your app. RStudio and Shiny are not available in Fall2020 images.

The SQLite Kernel lets users write plain SQL directly on a notebook. For more information on how to use it, check .

Dash is a powerful web based visualization tool for Python. By default, it runs a server on localhost so you can view dashboards on a web browser.

To use Dash inside of Jupyter Lab, you should use the appViewermethod from jupyterhub_dash. This will open a tab in Jupyter Lab instead of serving the app to localhost. See example below:

We provide all the Docker images used in JupyterHubs.

To use one of those images locally:

• Configure docker to use the gcloud command-line tool as a credential helper:

• Run the image locally: