How to use `stackyter` to run JupyterLab notebooks¶

This tutorial presents step-by-step instructions to execute Jupyter Notebooks configured to use the LSST software framework on hosts in CC-IN2P3 Login Farm. It is an alternative, older method to the one presented in How to execute LSST-enabled JupyterLab notebooks, which we recommend. However, both methods work.

A Jupyter Notebook is a web application that allows you to create documents that contain code (in particular Python code which uses the LSST software framework), narrative text, visualizations, etc. It is also a convenient way to explore data and document your work. You can find more information in the Jupyter project web site.

By executing Jupyter Notebooks at CC-IN2P3 you can explore the datasets interesting for LSST using the LSST software framework, without you needing to install on your personnal computer neither the LSST software nor the datasets.

Before being able to open a notebook, you need to:

Install Python 3
Install stackyter
Configure stackyter
Configure your SSH client

This installation is a one-time process.

Step 1: install Python¶

You need a working installation of Python in your personnal computer. We recommend the Anaconda distribution of Python 3.

Step 2: install stackyter¶

stackyter is a convenient tool to make easier launching Jupyter notebooks at a remote host, in particular at hosts in CC-IN2P3’s Login Farm. To install it on your personnal computer do:

pip install --upgrade stackyter

Further details and alternative installation options can be found in stackyter‘s documentation. Once installed we recommend you take a few minutes to configure it for your own needs as presented in the next step.

Step 3: configure stackyter¶

Create a YAML configuration file for instructing stackyter how to operate to launch Jupyter at CC-IN2P3. A sample of a valid configuration file follows:

{
    # Use the configuration named 'ccin2p3' by default. Useful if you have several configurations for
    # various remote servers in the same configuration file.
   'default_config': 'ccin2p3',

   # Configuration for using the LSST stack at CC-IN2P3
   'ccin2p3': {
        # Host where runs the Jupyter server. You can use a fully qualified host name
        # (e.g. cca.in2p3.fr) or a 'Host' entry of your SSH configuration file (typically ~/.ssh/config)
        'host': 'ccjupyter',

        # Flavor of Jupyter to use. Valid values: 'lab' or 'notebook'
        'jupyter': 'lab',

        # Absolute path of the directory (at CC-IN2P3) where Jupyter will save your notebooks.
        # NOTE: replace 'lsstuser' by your own login name
        'workdir': '/pbs/throng/lsst/users/lsstuser/notebooks',

        # Execute this list of commands before launching Jupyter. You can use this option
        # to setup the version of the LSST stack you want to use and to EUPS setup the
        # products you need in your work session
        'runbefore': [
           "source /cvmfs/sw.lsst.eu/linux-x86_64/lsst_distrib/w_2018_24/loadLSST.bash",
           "setup lsst_distrib"
        ],
   }
}

Copy-paste it, replace lsstuser by your own login name at CC-IN2P3 in the workdir entry and save it as $HOME/.stackyter-config.yaml.

There are other configuration options may find useful for your particular use case. You can find them all in stackyter official documentation. There are also some examples of configuration files.

Step 4: configure your SSH client¶

To configure and launch Jupyter at the remote host, stackyter uses the SSH client present in your personnal computer. In particular, in the configuration file above we used a host named ccjupyter which needs to be present in the SSH client configuration file. Add the entry below to your SSH configuration file (typically $HOME/.ssh/config):

Host ccjupyter
   Hostname cca.in2p3.fr
   User     lsstuser

If you have configured your computer to connect to CC-IN2P3 Login Farm without typing your password at every connection (see How to customize your SSH client), you may want instead to add the entry below to your SSH configuration file:

Host ccjupyter
   Hostname                  cca.in2p3.fr
   User                      lsstuser
   GSSAPIClientIdentity      lsstuser@CC.IN2P3.FR
   GSSAPIAuthentication      yes
   GSSAPIDelegateCredentials yes
   GSSAPITrustDns            yes

Important

Replace lsstuser above by your own login name at CC-IN2P3.

Please note that you can add other options to the ccjupyter host entry of the SSH configuration file as you need. Those options will automatically be used by stackyter when establishing the connection and launching Jupyter.

Launch Jupyter¶

Now you are ready to launch Jupyter with the command:

stackyter.py

Upon successfull launch of Jupyter on the remote host, stackyter displays serveral messages and you will see appear one highlighted message similar to the one below:

...
Copy/paste this URL into your browser to run the notebook localy
   http://localhost:20001/?token=7722079686b74117ef2f6cf7b425f91c8cf6cad34086f409

Point your web browser to the URL shown in the message. Please note that this URL is unique and changes every time you launch Jupyter.

You can now interact with your notebook. From within your notebook you can access the datasets of interest for LSST (see Datasets).

Once you are done, type Control-C to stop the remote Jupyter server and close the connection to the server.

How to use stackyter to run JupyterLab notebooks¶