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

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

There are two options:

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

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.

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.

Ⓢ Students should familiarize themselves with:

Ⓣ Teachers should familiarize themselves with:

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

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

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

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

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.

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.

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!

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.

• 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

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

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

• 1. GitHub Username, Password and Email. See

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

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

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.

You can follow instructions 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 .

Visit 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.

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 .

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

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 and

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.

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

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.

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.

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

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:

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

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.

1. Select the local File Browser from left sidebar

2. Create a new launcher using the New Launcher button

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

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

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

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

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:

• README

• CANVAS

• Write markdown cells inside the hub - commit and push

  • Student views inside jupyterhub

  • Could use for nicer diff

• 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>.. 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

• 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.

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: Learn Python3.

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 Learn Python3. 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.

Python3 Official Documentation:

Jupyter Notebook Official Documentation:

Jupyter Lab Official Documentation:

Basics Git Commands

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

Learn Git interactively:

GitHub

Atlassian Git Tutorial

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.

Ⓣ 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 .

Ⓢ 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.

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 and from the left navigation bar.

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

2. Click the"Clone or download" button

3. Copy the Git URL to your clipboard by clicking the clipboard button

Follow the steps in the page in the previous section

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

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

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

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

See to see how to generate links for distributing your repository

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

• Students can stay as outside collaborators for ever.

• There is no special consideration for shopping period

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:

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 .

1. Download the environment.nb.yml file

2. Create the environemtn using the file.

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 .

First try restarting the notebook kernel as seen in the . If the issue persists, restart your server by following the instructions in .

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".

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.

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.

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.

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

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

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

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.

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

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

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, , version control systems (like git/) or .

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.

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.

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()

• Julia ()

• R ()

• Ruby ()

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 . Most users don't need to know about these details, but it helps to understand that "kernels run code."

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

Internally, notebook documents are data with binary values 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 () using Jupyter's nbconvert utility.

Furthermore, any notebook document available from a public URL on or GitHub can be shared via . 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.

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.

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.