Welcome to your Getting Started Guide for JupyterHub. Your JupyterHub is designed to provide an environment to run Jupyter Notebooks for Python 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.

What Do You Get with your Hub?

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

What are Jupyter Notebooks (excerpt from Jupyter's official documentation)

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

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

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:~$

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

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.

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 Computing Policies Terms of Service Agreement

Sign In

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

1. Go to https://phys.jupyter.brown.edu and click "Sign in with Brown Gmail Login"

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.

Once connected, you should arrive at the JupyterHub home page as seen below. For more information about the menu buttons and their functionality, see the Interface Overview documentation.

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 .

• If you are experiencing technical issues, for instance, the Hub appears to be down or you have access issues, you can email ****

Your instructor will distribute Jupyter Notebooks via Canvas. In order to upload the notebook to your JupyterHub you must follow the following steps

1. Download notebook file from Canvas to your laptop

2. Upload from your desktop to JupyterHub:

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.

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.

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:

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.

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

Terminal displays no text

Close your JupyterHub tabs!

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.

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