Remote Code Editing

Visual Studio Code (often abbreviated as VS Code) is a cross-platform IDE maintained by Microsoft. Off-the-bat it works on all machines. At its core, it's extremely simple and does minimal text editing. However, it is highly customizable through professional and community-based extensions. Through these extensions, it has incredible support for almost all languages, and other customization such as specific keybindings for your most loved editors, e.g. Vim and Emacs. Other things worth highlighting are:

• Full git support, the integrated command line makes it easy to commit and upload your changes.
• Full Python IDE support with the Python Extensions
• Full Julia IDE development: https://www.julia-vscode.org/
• Remote Explorer Extension or Remote Development Extension

In this article, we will focus on a couple of extensions that enable coding on the HPC cluster from the comfort of your comfort zone.

1. Remote Explorer vs Remote Development - which one?
2. Remote Development Extension (External Docs)
3. Jupyter Notebooks in VSCode and on the cluster (External Docs)

DISCLAIMER: At this moment this does not work for Traverse because vscode-server does not natively support IBM Power9 architecture.

Remote Explorer vs Remote Development - which one?

VSCode has two plugin options for remote development that you can consider. If you are only interested in connecting to a remote server (e.g. adroit, della, etc.) and don't expect to need to connect to containers or use the Windows Subsystem for Linux (WSL), you can add the "Remote Explorer" extension with only includes "Remote - SSH" and "Remote - Tunnels". If you do expect to need container and/or WSL support, you should choose "Remote Development" as it includes everything in "Remote Explorer" plus "Dev Containers" and "WSL".

If you can't decide, it doesn't hurt to choose the more robust "Remote Development". Just know that instructions that follow for setting up a connection to a remote server using Remote Development should also work for Remote Explorer.

Remote Development Extension

The Remote Development Extension (RDE) allows the user to access the filesystem visually from their local machine through SSH. A non-gui vscode-server is launched on the remote machine that "sends" information from the remote machine to your local machine. This is shown in the Figure below.

For the user, this simply means after providing vscode with the needed credentials either "by hand" or with the .ssh/config, vscode will automatically open a new window, to the remote machine and the base directory is the default directory of the ssh command. Let's go through this step by step.

• Install vscode (if you haven't yet)
• Install the Remote Development Extension Pack - RDE Pack. The RDE should add a new menu button on the left-hand-side indicated by the red circle in the image below.
    

• Now, you should be able to connect to the remote machine using two ways. Either you connect manually by clicking on the `+` indicated by the green circle in the above figure and enter your ssh command as you usually connect, or you use the configuration of an existing ~/.ssh/config in the next section.
• vscode should open a new window that tries to connect to the remote machine. If successful, you should be able to open a specific folder containing your code just as you would on your local machine with the difference that you are exploring the file system of the remote machine.

(If it seems like your connection is hanging after your enter your password, sometimes that is because vscode is hiding the login terminal. It will nicely ask you for a password via a popup box but may not show the Duo prompt properly. To test if this is your issue, try opening settings and search for "show login terminal" and check the box. Now when you try to connect, it will happen through a terminal in the bottom of vscode.)

DISCLAIMER 1: Only connect to a specific folder on the clusters, do not connect to, e.g. /scratch/gpfs/ or /home/. These folders contain all users and all their files. Vscode frequently updates the file explorer. This update takes longer the larger the amount of subdirectories vscode has to scan. In the case of /scratch/gpfs/ or /home/, the amount of subdirectories is immense. In addition to only connecting to your own home directory, you may want to configure vscode on the server so that it doesn't scan the file systems. You can do this by modifying or creating the file:

$HOME/.vscode-server/data/Machine/settings.json

So that it includes those entries:

{
  "remote.autoForwardPortsSource": "output",
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "/scratch/gpfs/**": true,
    "/tigress/**": true,
    "/projects/**": true,
    "/home/**": true
  }
  [...the rest of the file, or nothing if you're creating a new file]
}

DISCLAIMER 2: There are a thousand reasons why your session may not start successfully. A first step in the debugging process should always be: 'Can I connect to the remote machine via `ssh` from the terminal to begin with?' If not, there's just no way that vscode could connect either. If that's possible the next step would be to try killing a possibly running vscode-server by opening the command palette and killing the remote session. On a Mac, Cmd+Shift+P to open the command palette, on Windows/Linux Ctrl+Shift+P, then Remote SSH: Kill VS Code Server on Remote Host ... , which will prompt a selection of possible hosts. Choose the host you want to connect to, e.g., @tigergpu.princeton.edu.

Editing your ~/.ssh/config

An example entry for connecting to della in the ~/.ssh/config could be:

  Host della.princeton.edu della
    User <netid>
    HostName della.princeton.edu
    ControlMaster auto
    ControlPersist yes
    ControlPath ~/.ssh/sockets/%p-%h-%r

where the Control* parameters enable us to stay connected to the cluster.

NOTE: You must manually create/ensure the existence of the directory ~/.ssh/sockets for this to work or you will get very cryptic error messages.

Adding a layer of complexity one could add a ProxyJump through tigressgateway, which ultimately removes the DUO requirement at every connection.

Host tigressgateway.princeton.edu tigressgateway
  HostName tigressgateway.princeton.edu
  User <netid>
  ControlMaster auto
  ControlPersist yes
  ControlPath ~/.ssh/sockets/%p-%h-%r
  ServerAliveInterval 300
  LocalForward 5901 adroit-vis.princeton.edu:5901
  LocalForward 5902 tigressdata.princeton.edu:5902
Host della.princeton.edu della
  User <netid>
  HostName della.princeton.edu
  ProxyJump tigressgateway.princeton.edu
  ControlMaster auto
  ControlPersist yes
  ControlPath ~/.ssh/sockets/%p-%h-%r

For details on suppressing DUO with a ProxyJump, please visit Removing Tedium.

Connecting to salloc sessions on individual nodes

DISCLAIMER: You must have ssh keys set up in order to ssh to a computer node. Compute nodes do not have access to password data and cannot verify ssh connections via passwords.

If you've started a session using salloc and would like to connect to it for debugging or general interactive coding, here's an example entry to add to ~/.ssh/config similar to above for della. First, create a ~/.ssh/sockets directory on the starting machine (e.g. your laptop) and then in ~/.ssh/config:

Host della-*
  ProxyJump della.princeton.edu
  User <netid>
  ControlMaster auto
  ControlPersist yes
  ControlPath ~/.ssh/sockets/%p-%h-%r

Let's assume that salloc gave you node "della-r4c4n1", you can now directly connect to "della-r4c4n1" in VS Code. If you configured della to jump through tigressgateway in the previous section, you would also avoid Duo (via multiple proxy jumps).

Jupyter Notebooks

Adroit, Della and Stellar

Open OnDemand Jupyter is available for these clusters. Please see our Jupyter page. This is a much better approach than trying to configure VS Code which tends to be error-prone.

Tiger

The Tiger cluster is 6 years old. After it is replaced in 2024, users will be able to use Open OnDemand Jupyter. Until then the directions below can can be used.

Using the Python extension, Jupyter notebooks are natively supported in VSCode. However, to run them on Tiger, we have to complete some extra steps:

This workflow lets you run Jupyter notebooks on tigergpu in vscode running on your laptop:

1. Remote Development Extension as described above.

2. Connect to, e.g., tigergpu (head node). To simplify the setup it is also helpful to load the anaconda module in my ~/.bashrc file on the cluster:

   module load anaconda/4.4.0

   This is needed because vscode requires an environment that contains Jupyter.

3. Run a simple notebook:

   print('hello world!'))

   on tigergpu’s head node to make sure everything works properly. It’s important to note here that the Python extension has to be installed on the remote server as well! So, go to the Extensions tab and double-check. Otherwise, you will not be able to select a environment-specific interpreter.

4. On tigergpu, request a salloc session:

   salloc -N 1 -n 4 -t 0:20:0

   Make note of the hostname of the node, e.g., tiger-i26c2n17. Note that for the purpose of the example, we did not ask for a GPU for the purpose of the example because it takes longer to get an allocation for GPU nodes. However, this setting works on GPU nodes.

5. On your laptop, add this entry to your ~/.ssh/config:

   Host tiger-compute
                               User <puid>
                               Hostname tiger-i26c2n17
                               ProxyJump tigergpu

   The User keyword is only important when your local username is different from your puid.

   One downside of that method is that you will need to modify your config file every time you get an salloc session. There might be ways around that. The good thing is that vscode seems to parse your config file when it gives suggestions for hosts to connect to.

6. On your local machine, you can open a remote vscode session on tiger-compute (vscode recognizes that host from the ~/.ssh/config).
7. Then, you should be able to run the notebook on the compute node.