Using VS Code on the Cluster

Table of Contents

• Introduction
• Running VS Code from Open OnDemand
  • Moving Files to and from the Local Machine to VS Code OnDemand
  • Run a Test Program
  • Troubleshooting
• Connect to Nova using a Registered Tunnel
  • Opening a Registered Tunnel
  • Close a Registered Tunnel
• SSH to nova-vscode from a Local VS Code Session
  • Run a Test Program

Introduction

Microsoft's Visual Studio Code (aka VS Code) is a popular source code editor and development environment with support for many different programming languages.  VS Code software includes a tool called VS Code Server that acts as a gateway from the VS Code session on your computer to the cluster so you execute your code on the cluster from within your VS Code session.

Below, we will demonstrate three different methods for connecting to VS Code Server and launching jobs on the clusters.  It is recommended that you use one of the first two options (Open OnDemand or Registered Tunnels), as they provide better performance.  However, SSH access to nova-vscode is also available for those who need it.

1. Running VS Code from Open OnDemand
2. Connect to Nova using a Registered Tunnel
3. SSH to nova-vscode from a Local VS Code Session

Running VS Code from Open OnDemand

1. Go to https://nova-ondemand.its.iastate.edu/ and log in.
2. From the Interactive Apps menu at the top select “VS Code Server”
   
3. Select the interactive partition, as well as any other desired options (the defaults are usually sufficient) and click “Launch”
4. A new VS Code session will automatically be created on one of the Nova compute nodes. This may take a few minutes depending on cluster demand. Once the session has been created, click “Connect to VS Code”.
   
5. Create a symbolic link to store extensions. This only needs to be done the first time you run VS Code OnDemand.
   1. Open the terminal window by going to File->View->Terminal
   2. In the terminal type the following commands, replacing <GroupName> with your group name and <UserName> with your user name.
      1. Create a folder in work for the VSCode extensions:
         mkdir -p /work/<GroupName>/<UserName>/.local/share/code-server
      2. Move any existing extension files to the new directory:
         mv ~/.local/share/code-server/ /work/<GroupName>/<UserName>/.local/share
      3. Create a symbolic link between the old extensions directory and the new one:
         ln -s /work/<GroupName>/<UserName>/.local/share/code-server  ~/.local/share/code-server
6. Install any desired extensions from the Extensions sidebar on the left-hand side. This only needs to be done the first time you run VS Code OnDemand, or whenever you need new extensions.
    

Moving Files to and from the Local Machine to VS Code OnDemand

1. Open the File Explorer sidebar on the left-hand side of VS Code.

   

2. To Download Files:
   1. Right-click on the file you would like to download from VS Code OnDemand to your local computer and select “Download…” from the menu. The file download will automatically start.
3. To Upload Files:
   1. Right-click on the folder where you would like to upload the file to and select “Upload…” from the menu.
   2. Select the file on your local computer in the File Upload dialog that appears and then click “Open”

Run a Test Program [Optional] 

1. This test program is written in Python. To run it, ensure the Python extension is installed. See step 6 of “Using VS Code on Nova OnDemand” if you need instructions for how to do this.
2. Create a new folder for your test code:
   1. In the Explorer sidebar on the left-hand side right-click and select “New Folder…”
   2. Give the folder a descriptive name, e.g. “vscode_test”
3. Make the new folder the working folder:
   1. From the menu button on the top left, select File->Open Folder…
   2. In the Command Palette that opens, type in the path to your folder and click “OK”
4. Create a new Python code file:
   1. From the menu button on the top left, select File->New File…
   2. In the Command Palette that opens, select “Python File”

5. Add the following test code to your new file:

   import socket
   
   computerName = socket.getfqdn()
   print(“This computer is: “ + computerName)

6. Save the file:
   1. From the menu button on the top left, select File->Save
   2. In the Command Palette that opens, type the desired file name, e.g. vscode_test.py, and click “OK”
7. To run the code, click the green play button in the top right.
    
8. The VS Code terminal will open if it wasn’t already and show the code output. The code output should read something similar to:
   This computer is: nova18-71
   1. The computer name will change based on which compute node you are connected to.
   2. If the computer name is “nova.its.iastate.edu” you have done something wrong! You should never run code on the Nova head node as it will result in poor performance.

Troubleshooting

The VS Code OnDemand Window Stopped Responding.

• Most likely your OnDemand session timed out. Return to the Nova OnDemand webpage and request a new session.
• If your session hasn’t timed out, the server may be time slicing (i.e. pausing your session to let other small jobs through). To prevent this, make sure you request the interactive partition when creating your OnDemand session.

Unable to Access the Nova OnDemand Webpage.

• Make sure you are connected to the Iowa State University network either on campus, or via the Iowa State VPN.

An Extension Isn’t Listed on VS Code OnDemand

• Due to licensing issues, the official Microsoft VS Code extensions marketplace isn’t available in VS Code OnDemand and it instead uses the Open-VSX extensions gallery. While most of the popular extensions are available in Open-VSX, some are not. To manually install an extension from the Microsoft VS Code extensions marketplace:
  1. Go to the website for the extension and select Download Extension->Linux x64
  2. Copy the file to one of the directories shared on Nova (e.g. your home or work directory).
  3. Open the terminal window in VS Code and send the following command (where you replace <Path> with the full path location of the vsix file downloaded for the extension): 
     code-server --install-extension <Path>

Return to Top of Page

Connect to Nova using a Registered Tunnel

Opening a Registered Tunnel

1. Open your local copy of VS Code.
2. Install the "Remote – Tunnels" extension from Microsoft using the Extensions sidebar on the left-hand side.
3. On the left-hand side, open the “Remote Explorer” sidebar and click the arrow next to “Sign in to tunnels registered with Microsoft”.
   1. If you are already signed into your Iowa State account in VS Code, this option will not appear and you may skip this step.
   2. If you receive a prompt that “The extension ‘Remote – Tunnels’ wants to sign in using Microsoft.” click “Allow".
      
4. A webpage should open to sign into Microsoft. You can use your Iowa State email (<NetID>@iastate.edu) to sign in.
   1. When using your Iowa State account to sign in, you should be redirected to the Iowa State single sign-on page to log in, if you are not already signed into Iowa State.
5. You should receive a page telling you that you are signed in and can close your web browser.
   1. By default, VS Code will remember your sign-in information so you should only have to do the sign-in steps the first time you use remote tunnels in VS Code.
6. Using a terminal (such as PowerShell on Windows or Terminal on Mac) SSH into nova.its.iastate.edu.  Do not use VS Code to ssh into nova.its.iastate.edu.
7. At the terminal, run the following command:
   launch-vscode-tunnel.sh
   1. By default, this script will request two CPU cores, on one of the interactive nodes of the cluster, for four hours.  You will have 8 GB of RAM available.  These settings should be sufficient for debugging and testing purposes.  If you need more resources, you can request them by passing sbatch arguments to the script.  However, be aware that the more resources you request, the longer it will take for the cluster to be able to allocate them for you.
8. You should see a message to open a web browser and go to https://microsoft.com/devicelogin and enter a code.  Do as instructed.
9. After entering the code, you will be asked to either log in or select an account to register the tunnel with.  Register it to your Iowa State account, unless you used a different account in step 4.
10. Once it is registered, return to your local VS Code instance.
11. Registered tunnels will show up in the Remote Explorer.  It should say something similar to nova21-1 running
    1. If your tunnel doesn’t appear immediately, press the refresh button next to “Remotes (Tunnels/SSH)”
12. When you hover over the tunnel, an arrow button will appear.  Click this button to connect to the tunnel.
13. You should now be running on one of the Nova compute nodes.  To confirm open a terminal from the menu Terminal->New Terminal.  In the terminal, run the command:
    hostname
    1. The command should respond with something similar to “nova21-1”.
    2. If the command returns with "nova.its.iastate.edu" you have connected to the wrong server and you will need to edit your settings to correct this!  You should never run code on the Nova head node will result in poor performance.

Close a Registered Tunnel

When you are done using a tunnel, it is important to close it to free up those resources for other users to use.  To do this:

1. Using a terminal (such as PowerShell on Windows or Terminal on Mac) SSH into nova.its.iastate.edu.  Do not use VS Code to ssh into nova.its.iastate.edu.
2. Run the following command, where <JobID> is the slurm job number that was displayed when you launched the tunnel:
   scancel <JobID>
   1. If you have forgotten the slurm job number, you can find it by running the following command.  Look for a job named “vscode-tunnel”.
      squeue --me

Return to Top of Page

SSH to nova-vscode from a Local VS Code Session

1. Before using SSH to access the Nova cluster from a local VS Code installation, a folder needs to be created in your work directory to store VS Code extensions on the remote computer. This is necessary because extension files can be quite large and could consume your entire home directory quota. To do this:
   1. Using a terminal (such as PowerShell on Windows or Terminal on Mac) SSH into nova.its.iastate.edu.  Do not use VS Code to ssh into nova.its.iastate.edu.
   2. In the terminal type the following commands, replacing <GroupName> with your group name and <UserName> with your user name.
      1. Create a folder in work for the VS Code extensions. Note: If you also use VS Code OnDemand, do not use the same folder you use for VS Code OnDemand extensions.
         mkdir -p /work/<GroupName>/<UserName>/.vscode-server
      2. Move any existing extension files to the new directory. If you have never accessed Nova from a local VS code installation, the ~/.vscode-server directory won't exist and this command will throw a “No such file or directory” error, in which case proceed to the next step.
         mv ~/.vscode-server /.work/<GroupName>/<UserName>/.vscode-s
      3. Create a symbolic link between the old extensions directory and the new one:
         ln -s /work/<GroupName>/<UserName>/.vscode-server ~/.vscode-server
   3. Once this is complete, you may close the SSH session.
2. Open the local installation of VS Code.
3. Install Remote Development extension.
4. On the left-hand side, open the Remote Explorer sidebar. 
   
5. When you hover over SSH, two icons will appear. Click the plus icon (“New Remote”) to add a new connection.
6. In the Command Palette that opens type the ssh information (where <UserName> is your user name) and hit enter.
   <UserName>@nova-vscode.its.iastate.edu 
   
7. Next you will be prompted to select a SSH configuration file to store the connection information in. Select the first option to make this connection available only for your account. On Windows this option should be C:\Users\<UserName>\.ssh\config and on Linux it should be /home/<UserName>/.ssh/config (where <UserName> is your local computer user name).
8. You can connect immediately by clicking “Connect” in the dialog that appears. In the future, this connection will be available under SSH in the Remote Explorer; however, you must restart VS Code for it to appear.
9. When you connect to the server you will receive prompts for the server fingerprint (first time only), one-time pass (GA) verification code, and password.
   1. Note: In some cases you may be asked for your verification code and password more than once. Make sure you wait for a new code to be generated before entering the verification code each time.
10. Confirm you are connected to the cluster by going to Terminal->New Terminal to open the terminal and running the command:
    hostname
    1. The command should respond with nova-vscode.its.iastate.edu.
    2. If the command returns with nova.its.iastate.edu you have connect to the wrong server and you need to change your ssh settings to use nova-vscode.its.iastate.edu! Running VS Code on the nova head node will result in poor performance.
11. While the nova-vscode node is good for debugging code, when running processor intensive data processing a compute node should be used. You can switch to running on a compute node by opening the terminal in VS Code and running the salloc command. For example:
    salloc -N 1 -n 1 -p interactive
    1. This will request access to one compute node, using one processor, and the interactive partition.

Run a Test Program [Optional]

1. This test program is written in Python. To run it, ensure the Python extension is installed.
2. Create a new folder for your test code:
   1. In the Explorer sidebar on the left-hand side right-click and select “New Folder…”
   2. Give the folder a descriptive name, e.g. “vscode_test”
3. Make the new folder the working folder:
   1. From the menu on the top left, select File->Open Folder…
   2. In the Command Palette that opens, type in the path to your folder and click “OK”
4. Create a new Python code file:
   1. From the menu on the top left, select File->New File…
   2. In the Command Palette that opens, select “Python File”

5. Add the following test code to your new file:

   import socket
   
   computerName = socket.getfqdn()
   print(“This computer is: “ + computerName)

6. Save the file:
   1. From the menu button on the top left, select File->Save
   2. In the Command Palette that opens, type the desired file name, e.g. vscode_test.py, and click “OK”
7. To run the code, click the green play button in the top right.
   
8. The VS Code terminal will open if it wasn’t already and show the code output. The code output should read something similar to:
   This computer is: nova-vscode.its.iastate.edu
   1. The computer name will change based on which compute node you are connected to.
   2. If the computer name is “nova.its.iastate.edu” you have done something wrong! You should never run code on the Nova head node as it will result in poor performance.

Return to Top of Page