Jupyter Notebooks Platform

Service description

JupyterLab is a web-based interactive development environment for Jupyter notebooks, code, and data. A Jupyter Notebook is a web application that allows you to create and share documents that contain code, narrative text, visualizations, and equations. It is then a convenient way to explore data, document and share your work. You can find more information in the Jupyter project web site.

The Jupyter Notebooks Platform is provided to any user having a computing account at CC-IN2P3.

For a general understanding of the tool, please refer to the official JupyterLab Documentation. If you experience any problem, please open a ticket to user support.

Access

You may access this service via the URL: notebook.cc.in2p3.fr. Access is granted through the EduGAIN federation or by entering your login and password from your computing account.

Warning

The connection to the Jupyter platform using EduGAIN requires not only to be known by the identity provider you are using, but also to own a valid computing account (which is not expired) and to be able to map both (the email attached to your EduGAIN identity should be the same as your primary email of your CC-IN2P3 account).

In case of problems, please use your computing account credentials to log in (you may also contact our user support for assistance).

After authentication, your JupyterLab notebook server will be launched and will persist until you logout (closing the web page doesn’t stop the notebook).

Once logged in, the notebook server will give you access to the following storage areas:

Note

SPS directories must be granted to be available through the notebook server. Ask our user support if you don’t find them.

The notebook interface is set on the user’s HOME directory. To navigate through the interface on the other directories listed above, create the appropriate symbolic links on your HOME. Example:

% ln -s /pbs/throng/ccin2p3 $HOME/throng_ccin2p3

The notebooks are provided with the Python interpreter included in a recent Anaconda distribution. If the default Python environment provided does not suit your needs, you may add your own.

The recipe to include such a custom kernel in your JupyterLab instance is given in the section below. CC-IN3P3 also provides specific scripts to help you set up custom kernels from the Python or ROOT environments available.

Final tips:
  • The notebooks are limited in RAM depending on your group. By default any group is granted 2 GB;
  • Inactive notebooks are destroyed after 72 hours;
  • Notebooks STDOUT and STDERR are sent to /var/log/notebookserver/notebookserver.log;
  • To stop your notebook server use File > Log Out.

Warning

To avoid possible Python versions conflicts, it is recommended to use the same Python version for the interpretator (for the kernel) that the version on which the JupyterLab software relies. The platform currently uses Python 3.8.5. If you are using custom kernels, it is recommended to build them again with a JupyterLab compatible Python version. If you have any question or problem, please contact our user support.

Add a custom kernel

In order to add a custom kernel, you need to provide a proper configuration file to Jupyter:

  1. First, create a new directory in $HOME/.local/share/jupyter/kernels/, let say python-3.7 (in this example we want to add a custom Python 3.7 kernel)

    If the directory tree does not exist yet, then you have to create it.

    % mkdir -p $HOME/.local/share/jupyter/kernels/python-3.7
    
  2. Go into that directory and create a kernel.json file

    % cd $HOME/.local/share/jupyter/kernels/python-3.7
    % vi kernel.json
    

    The kernel.json file will look like this:

    {
      "display_name": "conda3",
      "language":     "python",
      "argv": [
          "<PATH TO THE SCRIPT>/jupyter-helper.sh",
          "-f",
          "{connection_file}"
      ]
    }
    

    display_name is the name you want to give to your custom kernel, and will be displayed in your JupyterLab instance. You may want to update the language key as well. But the most important part is the jupyter-helper.sh script.

  3. The script jupyter-helper.sh will provide the requirements to set up the environment of the new kernel. This script will look like this:

    #!/bin/bash
    
    source /pbs/software/centos-7-x86_64/anaconda/3.7/etc/profile.d/conda.sh
    conda activate
    
    exec python -m ipykernel_launcher "$@"
    

    The first part sets up the required environment (here we are setting up an Anaconda environment), and the last line tells Jupyter how to start that new kernel.

Available scripts to add a custom kernel

CC-IN2P3 provides the jupyter-helper.sh script to set up custom kernels, for instance for the most recent ROOT or Python environments already provided in the software area. The full list of available scripts can be found in the following file:

/pbs/software/centos-7-x86_64/jupyter_kernels/jupyter_helper_scripts

For Julia, Golang, R and C++/ROOT langages, ready-to-use custom kernels are available in the directory:

/pbs/software/centos-7-x86_64/jupyter_kernels

In order to use one of them, you simply need to copy the given kernel directory to your own $HOME/.local/share/jupyter/kernels/ area:

% cp -r /pbs/software/centos-7-x86_64/jupyter_kernels/Golang-1.13.6 $HOME/.local/share/jupyter/kernels/.

JupyterLab extensions available

A few JupyterLab extensions are available:

  • Voilà, provides HTML preview of notebooks, this preview can be displayed either in JupyterLab directly, or in a new browser tab (in this case, make sure to allow pop-up windows), the interactivity provided by the extensions ipywidgets and ipympl (see below for a short description of these extensions) can be preserved, for more detail please see the official Voilà repositery,
  • Jupytext, allows to synchronise notebooks in various other file formats, such as Markdown, in order to ease the storage of such notebooks and file in Git repositery, for more detail, please see the official Jupytext repositery,
  • ipywidgets, enhances interactivity with the notebook thanks to dedicated widgets, see the official ipywidgets repositery,
  • ipympl, introduces interactivity with plots made using matplotlib, see the official ipympl repositery,
  • jupyter-lab provides preview of LaTeX documents (*.tex files) inside a notebook, see the official JupyterLab repositery,
  • LaTeX can also be used in legends for matplotlib and to convert and export notebooks to PDF files.

If you need assistance to use these scripts, or need to set up your own custom kernel which would suits your needs, please contact our user support.