Jupyter notebook

Although Argon is unsuitable for providing a full JupyterHub installation, you can run a Jupyter notebook on Argon and connect a web browser to it. This connection requires creating a network path, consisting of at least one SSH tunnel, between the system running your notebook and the system running the web browser. Thus to use a browser running on your local computer, one end of the tunnel needs to be on your computer.

The required SSH software and configuration are typically present on Linux and Mac workstations/notebooks by default, so the instructions on this page describing tunnel configuration should function there without additional configuration. A variation commonly used on Windows systems is also shown. The instructions for selecting a Python environment and running jupyter are specific to the Argon HPC system.

For most Argon use, it's typical to connect to "argon.hpc.uiowa.edu", resulting in a login session on whichever of Argon's login nodes least recently served a new connection. However, to configure the tunnel for your jupyter notebook connection, you must ensure you consistently connect to the same login node in multiple steps. Therefore, for each connection you should use the "true" name one of Argon's login nodes instead of "argon.hpc.uiowa.edu":

• argon-login-1.hpc.uiowa.edu
• argon-login-2.hpc.uiowa.edu
• argon-login-1.hpc.uiowa.edu
• argon-login-2.hpc.uiowa.edu

The example here assumes shows how to connect using the browser on your local computer, and uses argon-login-1.hpc.uiowa.edu only as a specific example.

First, connect to your chosen login node:

ssh argon-login-1.hpc.uiowa.edu

In your session on the login node, you must select the version of python that you want to use. Run the following command to see the available python environment modules.

module -tr avail ^python

Load the selected python environment module.

module load python/2.7.13

Now, start a jupyter notebook, but without a browser (because you will use a browser on your local machine):

jupyter notebook --no-browser

This makes launches a notebook instance, makes it available at a particular port on the system running, and prints the port in the terminal. It tries to use port 8888 first, but it if something else (such as another jupyter notebook) is already using a port, then it tries higher ports in sequence until it finds the next one available. The output will look something like the following:

For the next step, note the reported port, namely the number between "localhost:" and "/". In this example, it's 8889.

The port number is essentially a public address which anyone can use, even unintentionally (by typo, for example). The token is like a password; it only applies to the specific notebook running there (the one you launched just now), and it prints only in your specific terminal.

We will next set up an SSH tunnel from a port on your local machine to the remote machine. This will allow your browser to connect to the port on your local machine, and SSH will transfer the traffic between your system and the remote system to communicate with your notebook instance. By default, any computer should be able to refer to itself using the name "localhost", and this example follows that standard convention.

Ordinarily, all Web browsers try connecting to the standard Web port by default. But your notebook on the remote system is connected to its own unique port there, so we'll specify a parameter to alter the destination port to match the port reported in the previous step.

The port on your system is independent of the port on the remote system running your notebook, but you may find it convenient to use the same port number. Doing so will let you use the URL presented by some versions of jupyter notebook without modification, such as in the example above.

Open another terminal session on your local workstation or laptop and run the following command:

ssh -N -L 8889:localhost:8889 argon-login-1.hpc.uiowa.edu

That will configure a tunnel, from Local entry port 8889 on "localhost" (your system), to "argon-login-1.hpc.uiowa.edu", with destination port 8889 (your notebook's port).

The process above should work on Linux and Mac systems without modification, but the process for Windows systems can vary.

In the left pane, expand "SSH" and select "Tunnels":

To create your new forwarded connection, enter the local port as the "Source" port, then the hostname and port number as the "Destination", localhost:8889 as in the example above:

Click "Add" so that the new configuration is displayed as an entry listed in the "Forwarded Ports" box as shown here:

Click on the "Session" tab on the left side of the window:

Then open a normal SSH connection to your chosen login node:

The remaining steps and usage should be the same regardless of your tunnel.

After port forwarding is set up and running on your system, copy the URL reported when you launched your jupyter notebook, which resembles this:

http://localhost:8889/?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Paste it into the browser running on your local machine, modify it if your chosen version of jupyter reported in a different form, and hit enter. That should establish a session connected to your jupyter notebook server program, allowing you to interact with the notebook normally.

When you are finished using the notebook,

1. Control-C in the local session with the ssh port forwarding to stop forwarding
2. Control-C in the shell session on the remote node where your jupyter notebook is running