Connecting to PPAN and Running Jupyter Notebooks in VS Code

Visual Studio Code provides extensions called Remote-SSH and Jupyter that allow to access files on a remote machine and run Jupyter Notebooks, respectively. Using these two extensions, you can edit and run files and Jupyter Notebooks on PPAN from a VS Code installation on your local Machine. This guide assumes that

1. You can access PPAN via SSH from your device
2. You are connecting from Linux or Mac ( Windows Instructions will hopefully be added at a later date)
3. You already have VS Code installed on your device

Note that this guide focuses on access PPAN and Jupyter Notebooks within VS Code. If you would just like to access PPAN, see the Remote Access page. If you would just like to run Jupyter Notebooks on your local machine, see our Using Jupyter Notebooks on PPAN page.

This guide is heavily based on a earlier guide put together by Max Pike and Marc Prange - see here for more details.

Connecting to Analysis in VS Code ( Linux / Mac )

Setting Up SSH Keys to connect to Analysis

You will need to set up an ssh key pair between your local machine and analysis in order to connect to analysis with the Remote ssh tool. If you already have an ssh key that you would like to use for this connection, feel free to skip ahead to step 4. Otherwise, to setup up the key pair:

1. Open up a terminal and run:

ssh-keygen

2. When asked where you want to store the ssh key, hit enter to accept the default location.

   a.) If a key already exists in the default location, you will receive a warning asking you if you would like to overwrite this key. Do not overwrite the key if you are using it for anything else. Instead, skip to step to step 4.

3. You will then be prompted to select a password for the key. While not strictly necessary, it is recommended. Be sure to choose something you will remember, as you will need it every time you connect to analysis.

4. If you used the default location specified above, you should see a file in your ~/.ssh directory named something along the lines of ~/.ssh/id_rsa.pub or ~/.ssh/id_ed25519.pub. Type the following command to view this .pub file:

cat ~/.ssh/id_rsa.pub # or cat ~/.ssh/id_ed25519.pub, depending the file type that showed up in the default loca. tion from earlier

Make sure you view the .pub file, and not the default file printed earlier. Of course, if you choose to store your keys in different location or name than the default, cat that .pub file instead.

5. Copy the output, then connect to PPAN

6. Open the file ~/.ssh/authorized_keys on PPAN, and paste the output from step 4 here.

Configuring Tunnels to Access Analysis

Now that you have an ssh key pair setup, you need to create SSH tunnels that will allow you to connect to PPAN via the Remote-SSH extension.

1. Open up a terminal, and connect to PPAN using ssh. After you are prompted to select a host, you should see two lines mentioning local and remote port numbers:

You will now be connected to the lightest-loaded analysis host.
To select a specific host, hit ^C within 5 seconds.
Local port XXXXX forwarded to remote host.
Remote port YYYY forwarded to local host.

2. Write down or copy both of these numbers. and open up the ~/.ssh/config file on your local machine. Paste information for the following hosts into that document, or modify the following sections to contain this information if these sections already exist:

Host analysis
  HostName                analysis-rsa.princeton.rdhpcs.noaa.gov
  User                    First.Last
  ControlMaster           auto
  LocalForward            XXXXX localhost:XXXX
  RemoteForward           YYYY localhost:22

Host local_analysis
  HostName                localhost
  Port                    XXXXX
  User                    First.Last
  PasswordAuthentication  yes

Where XXXXX and YYYY refer to the local and remote ports from earlier, and First.Last is your GFDL username. If you are using a non-default name or location for your keys, you may also have to add a IdentityFile /path/to/private/ssh/key line to your local_analysis host definition

Connecting to VS Code with the Remote SSH Extension

1. Open up VS Code, and install the Remote SSH Extension. If it installs correctly, you should see a new tab on the left side of of your window labelled Remote Explorer:

2. Open the Remote explorer tab. You should see a list of hosts defined in your ~/.ssh/config file, including the local_analysis and analysis hosts defined earlier. Click on the arrow in the local_analysis tab to open a connection to analysis in the current window

3. If everything is set up a correctly, you will soon be prompted to enter the password for your ssh key from a dropdown window at the top of your screen. Enter the password you set this key earlier into this window

If you are successfully connected, you should now seen a blue tab at the bottom left of the screen that says 'SSH:local_analysis`. You can then open up a terminal within VS Code to access analysis as usual or open up the explorer window in VS Code to explore your files in analysis within VS Code!

Running Jupyter Notebooks in VS Code ( Linux / Mac )

Once you setup Remote SSH within VS Code, you should have access to all of your files on analysis from the explorer window. In particular, you should be able to access and open Jupyter Notebooks stored on analysis from the explorer window.

To access your python environments and IPython Kernels within VSCode, you will need to install the Jupyter extension in VS Code - you will likely be prompted to install this and other extensions the moment you open up a Notebook anyways. Once it is installed you should also be able to access your python environments on Analysis by clicking the Select Kernels button at the top right corner of the notebook in VS Code.