JupyterHub: Difference between revisions

Note: JupyterHub could have also been configured to force a specific user interface. This is usually done for special events.

JupyterLab is now the recommended general-purpose user interface to use on a JupyterHub.

From a JupyterLab server, you can manage your remote files and folders,

and you can launch Jupyter applications like a terminal, (Python 3) notebooks, RStudio and a Linux desktop.

When JupyterLab is ready to be used, the interface has multiple panels.

[[File:JupyterLab_HomeTab.png|thumb|Default home tab when JupyterLab is loaded]]

* In the ''File'' menu:

** ''Hub Control Panel'': if you want to manually stop the JupyterLab server and the corresponding job on the cluster. This is useful when you want to start a new JupyterLab server with more or less resources

* Most other menu items are related to notebooks and Jupyter applications

* ''File Browser'' (folder icon):

** This is where you can browse in your home, project and scratch spaces

** The last sub-panel is the list of ''Available modules'', similar to the output of <code>module avail</code>. By clicking on a module's name, detailed information about the module is displayed. By clicking on the ''Load'' link, the module will be loaded and added to the ''Loaded Modules'' list.

* The ''Launcher'' tab is opened by default

** It contains all available [[#Prebuilt_Applications|Jupyter applications and notebooks]], depending on which modules are loaded

* By clicking on the icons, this brings you to the ''Running Terminals and Kernels'' tool.

JupyterLab offers access to a terminal, an IDE (Desktop), a Python console and different options to create text and Markdown files. This section presents only the main supported Jupyter applications that work with the Compute Canada software stack.

[[File:JupyterLab_Launcher_Julia.png|thumb|Julia console launcher button]]

[[File:JupyterLab_Launcher_Python.png|thumb|Python console launcher button]]

[[File:JupyterLab_Launcher_Terminal.png|thumb|Terminal launcher button]]

To enable the ''Julia 1.x'' console launcher, an <code>ijulia-kernel</code> module needs to be loaded. When launched, a Julia interpreter is presented in a new JupyterLab tab.

The ''Python 3.x'' console launcher is available by default in a new JupyterLab session. When launched, a Python 3 interpreter is presented in a new JupyterLab tab.

This application launcher will open a terminal in a new JupyterLab tab:

* The terminal runs a (Bash) shell on the remote compute node without the need of an SSH connection

** Paste operation: press Ctrl+V

To enable the ''Julia 1.x'' notebook launcher, an <code>ijulia-kernel</code> module needs to be loaded. When launched, a Julia notebook is presented in a new JupyterLab tab.

[[File:JupyterLab_Softwares_ScipyStack.png|thumb|Searching for scipy-stack modules]]

If any of the following scientific Python packages is required by your notebook, before you open this notebook, you must load the <code>scipy-stack</code> module from the JupyterLab ''Softwares'' tool:

* And many more (click on the <code>scipy-stack</code> module to see all ''Included extensions'')

Note: you may also install needed packages by running for example the following command inside of a cell: <code>!pip install --no-index numpy</code>

* For some packages (like <code>plotly</code>, for example), you may need to restart the notebook's kernel before importing the package.

* The installation of packages in the default Python kernel environment is temporary to the lifetime of the JupyterLab session; you will have to reinstall these packages the next time you start a new JupyterLab session. For a persistent Python environment, you must configure a custom Python kernel.

To open an existing Python notebook:

* Go back to the ''File Browser''

** An IPython kernel will start running in background for this notebook

To open a new Python notebook in the current ''File Browser'' directory:

* Click on the ''Python 3.x'' launcher under the ''Notebook'' section:

** A new IPython kernel will start running in background for this notebook

[[File:JupyterLab_Launcher_OpenRefine.png|thumb|OpenRefine launcher button]]

To enable the ''OpenRefine'' application launcher, an <code>openrefine</code> module needs to be loaded. Depending on the software environment version, the latest version of OpenRefine should be loaded:

* With <code>StdEnv/2018.3</code>, load module: <code>openrefine/3.3</code>

This ''OpenRefine'' launcher will open or reopen an OpenRefine interface in a new Web browser tab:

* It is possible to reopen an active OpenRefine session after the Web browser tab was closed

* The OpenRefine session will end when the JupyterLab session will end

[[File:JupyterLab_Launcher_RStudio.png|thumb|RStudio launcher button]]

To enable the ''RStudio'' application launcher, the following three modules need to be loaded:

# <code>rstudio-server</code>

Depending on the software environment version, you should load the following two modules (<code>r</code> is loaded automatically):

* With <code>StdEnv/2020</code>, it is not yet supported

* With <code>StdEnv/2016.4</code>, load modules: <code>gcc/7.3.0</code>, <code>rstudio-server/1.2.1335</code>

This ''RStudio'' launcher will open or reopen an RStudio interface in a new Web browser tab:

* It is possible to reopen an active RStudio session after the Web browser tab was closed

* The RStudio session will end when the JupyterLab session will end

[[File:JupyterLab_Launcher_VSCode.png|thumb|VS Code launcher button]]

To enable the ''VS Code'' (Visual Studio Code) application launcher, a <code>code-server</code> module needs to be loaded. Depending on the software environment version, the latest version of VS Code should be loaded:

* With <code>StdEnv/2018.3</code>, load module: <code>code-server/3.4.1</code>

This ''VS Code'' launcher will open or reopen the VS Code interface in a new Web browser tab:

* For a new session, the ''VS Code'' session can take up to 3 minutes to complete its startup.

* The VS Code session will end when the JupyterLab session will end

[[File:JupyterLab_Launcher_Desktop.png|thumb|Desktop launcher button]]

This ''Desktop'' launcher will open or reopen a remote Linux desktop interface in a new Web browser tab:

* The desktop session will end when the JupyterLab session will end

Most JupyterHub errors are caused by the underlying job scheduler which is either unresponsive or not able to find appropriate resources for your session. For example:

* A "time-out" error message when starting a JupyterLab session: