Skip to content

Jupyter hub and notebooks

Documentation based on frequently asked questions

Jupyter on Maxwell

The easiest way to run Jupyter Notebooks on the Maxwell cluster is to use the Jupyter Hub portal.

Alternatively, a notebook server can be manually started on Maxwell, and port forwarding can be used to direct a local web-browser to that server.

Both approaches will be explained in the following.

Log in to Jupyter Hub on the Maxwell cluster using your DESY account. Once logged in, perform the following steps:

  • Choose a suitable partition on Maxwell from the upper drop-down menu; the choice should target one that your group has access to. Note that if you experience start-up problems with one partition, you may want to try another one.

Partition Node Type Description Maximum Duration
JHub Shared Lightweight workloads 7 days
EXFEL Dedicated For EuXFEL staff 8 hours
UPEX Dedicated For EuXFEL users 8 hours
upex_PPPP Dedicated Proposal-specific reservation 8 hours

You will automatically have a symbolic link in your home directory to GPFS, use this to access your proposal user or scratch. e.g. /gpfs/exfel/exp/$INST/$CYCLE/p$PROPOSAL_ID/usr -> ~/gpfs/exfel/exp/$INST/$CYCLE/p$PROPOSAL_ID/usr

Warning

Remember to disconnect by clicking on Control Panel and then Stop My Server to free the reserved node.

This is the easiest way to run Jupyter Notebooks on the Maxwell cluster (it does not require port forwarding or machine reservations). When you load a notebook you will automatically see xfel kernels are available, these kernels provide access to the EuXFEL python environment set up with some useful packages for data analysis.

More Information

Concerning the display quality, another advantage of using Max-JHub is that you don't need X-forwarding, and you can often get better rendering using your 'own' browser on your computer than to X-forward the browser window of the browser provided on the Maxwell nodes.

Manual Jupyter on Maxwell

The following protocols are useful if you cannot use JupyterHub, or want to have more fine grained control about the resources you use in your notebook session.

If you want to manually start a Jupyter server, set up your own python environment to do so, or activate an existing environment as described in Software - Module System to run Jupyter out of.

From Inside the DESY Network

  1. Allocate a node, see Offline Analysis - Allocating Resources for more information.
  2. SSH to that node, forwarding the ports you will be using for the Jupyter server, and start up Jupyter: 
    # From your local machine:
ssh -L $JPORT:localhost:$JPORT $NODE
# Activate the environment you will be using to run Jupyter
jupyter-lab --port $JPORT --no-browser
  3. Then open a browser window on your machine and connect to the server at the url https://localhost:$JPORT

  4. If you haven't set a password before, the standard output in the terminal will end with a text block providing a token, copy-paste that token or directly navigate to that URL: 

    To access the notebook, open this file in a browser:
  file:///home/dallanto/.local/share/jupyter/runtime/nbserver-14812-open.html
Or copy and paste one of these URLs:
  http://localhost:8432/?token=eac81f1482be0112caee9aff8eb13745f976109f0c80f9c6
or http://127.0.0.1:8432/?token=eac81f1482be0112caee9aff8eb13745f976109f0c80f9c6
    If for some reason the terminal text from the server startup is not available, one can also retrieve the token by typing jupyter-notebook list to a command-line prompt of the node where the notebook server runs.

    However, if a password has been set, the authentication dialogue will simplify and you will be asked for that password only.

From Outside the DESY Network

If you are connecting from outside the DESY network, you will have to perform the tunnelling steps twice, once through a gateway node and then once to your allocated node. Apart from that, the steps are the same as before:

# From your local machine:
ssh -L $JPORT:localhost$JPORT max-exfl-display.desy.de  # or any other gateway
salloc --partition=exfel  # Allocate node
ssh -L $JPORT:localhost:$JPORT $NODE
jupyter-lab --port $JPORT --no-browser

Now you can connect to the server in your browser as before.

Important

If your laptop is connect to eduroam, you are outside the XFEL/DESY network, and need to follow instructions in From Outside the DESY Network

From Hutch Computers

The hutch computers are isolated from the internet, but it is possible to set a proxy to access the internet - including Max-JHub.

To fix this you must disable the SOCKS proxy, the correct settings are:

  1. Open preferences
  2. Scroll down, click network settings
  3. Tick "Manual proxy configuration"
  4. Set the HTTP Proxy to exflproxy01.desy.de and the port to 3128
  5. Make sure that the "SOCKS Host" and "Port" entry is empty
  6. Tick "Also use this proxy for FTP and HTTPS"
  7. Select OK to save these settings

Note that there is an additional issue with Firefox where, even though you deleted the url and the setting was applied, the UI still shows an entry. If this happens you can check the actual setting by going to about:config in Firefox, searching for network.proxy.socks, and deleting the values for network.proxy.socks and network.proxy.socks_port.

Jupyter on the Online Cluster

There are some use cases where you might want to run Jupyter on the Online Cluster to perform data analysis before the data is transferred to Maxwell.

Via ONC JupyterHub

Separate to Maxwell, Jupyter Hub is set up on the Online Cluster as well. Each SASE ONC has its own Jupyter Hub server running. The following nodes should be used:

More Information

Full details are available in Online Analysis - Infrastructure

Instrument Node Node (GPU)
SPB sa1-onc-spb sa1-ong-spb
FXE sa1-onc-fxe sa1-ong-fxe
MID sa2-onc-mid sa2-ong-mid
HED sa2-onc-hed sa2-ong-hed
SCS sa3-onc-scs sa3-ong-scs
SQS sa3-onc-sqs sa3-ong-sqs

If you are using the hutch computers, or a computer on the control network, then you can connect to the respective ONC node directly in your browser (e.g. https://sa1-onc-spb, https://sa1-onc-spb.desy.de).

If you are outside the control network, then you will have to forward ports through the gateway first (as in the Outside the DESY Network case), e.g. ssh -L 8080:sa1-onc-spb:443 exflgateway.desy.de -N then going to https://localhost:8080 (you will see a certificate warning due to the site being served to localhost instead of its actual domain, it is safe to ignore this).

Manual Jupyter on ONC

As on Maxwell, you can run your own Jupyter session on the ONC nodes. Follow the instructions given for Jupyter from Outside DESY or Jupyter from Inside DESY, with the remote node being the desired ONC node instead of a Maxwell node.