Content Comparison

Although Argon is unsuitable for providing a full JupyterHub installation, you can run a Jupyter notebook 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 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-3.hpc.uiowa.edu
• argon-login-4.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.

1. Generate script for running Jupyter Notebook:

   Code Block
   $ mkdir $HOME/bin $ echo -e '#!/bin/bash\njupyter notebook --ip $(hostname -f) --no-browser --port=8080' > $HOME/bin/notebook.sh

   In this step, you create a folder containing your private scripts including notebook.sh. In the second line, you will generate the script for running Jupyter Notebook. In this example, you set the port number to 8080, which can be replaced with any four-digit number.
   
   The notebook.sh will have the lines below:

   Code Block
   #!/bin/bash jupyter notebook --ip $(hostname -f) --no-browser --port=8080

   You can reuse this script later as well and modify the port number if needed.
   

2. Convert the script to be executable

   Code Block
   $ chmod +x $HOME/bin/notebook.sh

3. Load required modules

   Code Block
   $ module load python $ module load py-jupyter

$ module spider python

$ module load numpy
$ module load matplotlib

3. Start a Jupyter notebook on the compute nodes using the SGE scheduler

   Code Block
   $ qrsh -q UI -N Jupyter -pe smp 2 -cwd $HOME/bin/notebook.sh

   In this example, it requests UI queue with 2 slots (-pe smp 2) and the name of the job is Jupyter. The -cwd flag indicates that the Jupyter Notebook will access the current directory. You can modify the queue, number of slots, and the Job name.
   
   If it successfully launches the Jupyter Notebook on the compute node, it will print out the logs like below:

   Image Added

   In this example, it runs on argon-itf-bx47-36.hpc node with forwarding the port to 8080. The token should be memorized to access the notebook in your local browser (the characters in the blue box above).
   
   The port number is essentially a public address

...

3. that 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.

4. 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

...

4. 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

...

4. 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:

...

4. Code Block
   $ ssh -N -L

...

4. localhost:

...

4. 8080:

...

4. argon-itf-

...

4. bx47-36.hpc:8080 HawkID@argon.hpc.uiowa.edu

   That will configure a tunnel, from Local entry port

...

4. 8080 on "localhost" (your system), to

...

4. argon-

...

4. itf-bx47-

...

4. 36.hpc

...

4. node, with destination port

...

4. 8080 (your notebook's port) through the login node. The destination compute node and the port should match what you set in the previous steps.

5. Open a browser on your local computer and go to http://localhost:8080. This may require you to enter a token for secure access. You will need to copy the token (in step 3) and paste it.
   

$ jupyter notebook list

$ qstat -u your_HawkID

Additional Tip

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":Image Removed

...

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 it was 8080):Image Removed

...

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

...

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

...

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

...

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 notebookJupyter 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 Jupyter is reported in a different form, and hit enter. That should establish a session connected to your jupyter 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