This document describes how to use TJ's JupyterHub instance

What is JupyterHub?

JupyterHub is a fully online IDE that is very similar to Google's Colab interface. JupyterHub's uses varies from simple text file editing to large IPython notebooks. This document will mainly focus on the advanced features of JupyterHub since the more simple features are easily discover-able through the interface and are fairly self-explanatory

How do I access JupyterHub?

TJ's JupyterHub instance is available at https://jupyterhub.tjhsst.edu. You will be redirected to Ion to complete authentication and afterwards you will be placed in a queue to wait for your own server to spawn. Our instance is configured such that your server may be spawned on one of 53 different machines. Even though your server is spawned on random machines, all your files are stored in a common location: /cluster/<username>.

Advanced Features

Python Interfaces

After logging in you may be greeted with a "Launcher" tab. This tab will have multiple options, including:

  • Python Notebook

  • Python Console

  • Terminal

The Python Notebook and Python Console are two separate interfaces, and you may experiment with either of them.

As you see in the top two rows, the options "Notebook" and "Console" are available. Notice how they are both named "Python (default)"

Both of these Python interfaces are based in the "default" Python environment, meaning they have the default packages. In most cases the default packages will suffice, but if you need to install custom packages read the instructions below:

Creating Conda Environments

Both the Python Notebook and Console are backed by Conda environments. Familiarize yourself with Conda environments before reading on.

To create a personal custom Conda environment run the following:

On infocube or any cluster node run the following in your home dir (/cluster/<your_csl_username>)

conda create --name my_personal_environment ipykernel
  • the --name parameter can be anything you wish (in this case my_personal_environment)

  • ipykernel is REQUIRED at the end

After creating the conda env, activate it:

conda activate my_personal_environment
  • Replace my_personal_environment with the environment name you previously chose

Finally add the environment to JupyterHub:

python -m ipykernel install --user --name "my_env" --display-name "My Env"
  • the --name and --display-name parameters can be anything you wish

After running the previous commands your launcher should now look like this:

Notice how a second option for both Notebook and Console is now available. The names match the "--display-name" parameter in the previous step

Now you have created a personal environment you have total control of. You may use conda to install any custom packages you wish. Be sure to click on your new Python Notebook/Console option (not the default option) if you wish to access your custom environment.

Removing Environments

Removing environments is a permanent action and cannot be reversed!

Removing the conda environment is simple:

conda env remove -n my_personal_environment

Removing the entry is a little more involved:

rm -r /cluster/<username>/.local/share/jupyter/kernels/<name>
  • The <name> parameter must match the --name parameter passed to the python -m ipykernel ... step, NOT --display-name! You may also ls around in this directory to find your matching environment and then rm -r the directory

  • After removing the directory, reload the JupyterHub site and the entry will now be removed