VS Code

Creating a VS Code Server task on the login nodes can consume a significant amount of memory. If multiple users do this, this could potentially CRASH the login nodes, thus preventing all 1000+ OSCER users from logging in!

If you need help with the steps below, you're welcome to join OSCER's Zoom help sessions, held every Thursday from 1:00 PM to 3:00 PM and Friday 1:00 PM to 2:00 PM.

If you're reading this, you're likely already familiar with the usefulness and strong ecosystem support of VS Code as an IDE (Integrated Development Environment). This guide explains how to properly debug code (particularly Python scripts) on OSCER using the VS Code application installed on your local computer. Before proceeding, make sure you have read the cautionary note above.

At the time this guide was written, the latest release of Visual Studio Code is version 1.124.0. Please download the VS Code Desktop package for your operation system using the links below. In Step 5, download the matching VS Code CLI version corresponding to the desktop version you installed.

The link  below are based on Microsoft's official instructions for downloading specific VS Code releases.

Recommended Download Format

We recommend downloading the compressed package version of VS Code (.zip for Windows and macOS, .tar.gz for Linux). After downloading, simply extract the archive and launch the VS Code executable. No installation is required, and you do not need administrative or root privileges.

This setup only needs to be performed once. For future sessions, you can launch VS Code directly from the extracted directory.

Download Links

• For Windows:
  https://update.code.visualstudio.com/1.124.0/win32-x64-archive/stable
• For Linux:
  • Debian/Ubuntu:
      https://update.code.visualstudio.com/1.124.0/linux-deb-x64/stable
  • RHEL/Fedora/SUSE:
      https://update.code.visualstudio.com/1.124.0/linux-rpm-x64/stable
• For MacOS:
  https://update.code.visualstudio.com/1.124.0/darwin-universal/stable

Create a Portable Installation (Recommended)

After downloading and extracting the VS Code package, we recommend configuring it as a portable installation. This allows it to run independently from any other VS Code installation already present on your computer.

To create a portable installation:

• Windows or Linux: Create a directory named data in the extracted VS Code directory (the same location as the code or code.exe executable).
• macOS: Create a directory named code-portable-data alongside Visual Studio Code.app.

For more information, see: https://code.visualstudio.com/docs/editor/portable

Note: Whenever you change your VS Code CLI version, remove the following directories before reconnecting, as described in the Troubleshooting section:

• ~/.vscode
• ~/.vscode-server

Start VS Code on your local computer. If you downloaded the compressed VS Code package as recommended, simply launch the executable from the extracted directory. On Windows, run Code.exe; on Linux, run code; and on macOS, open Visual Studio Code.app.

Once VS Code is open, select the Extensions view from the left sidebar (or press Ctrl+Shift+X on Windows/Linux or Cmd+Shift+X on macOS). Search for Remote - Tunnels and install the extension published by Microsoft.

This step only needs to be completed once.

VS Code Remote Tunnels requires a GitHub account. If you do not already have one, create an account at https://github.com/signup and follow the registration instructions. You will need to provide an email address and create a password.

This step only needs to be completed once.

Windows users can follow the OSCER MobaXterm instructions for connecting to Sooner.

Linux and macOS users can open a terminal and connect by running:

ssh <username>@sooner.oscer.ou.edu

Enter your OSCER password when prompted.

To start a VS Code tunnel from an OSCER compute node, you will need the VS Code Command-Line Interface (CLI). Download the CLI for VS Code version 1.124.0 using the command below. If you are using a different VS Code release, ensure you download the matching CLI version.

curl -Lk 'https://update.code.visualstudio.com/1.124.0/cli-alpine-x64/stable' --output vscode_cli.tar.gz

After the download completes, extract the archive and remove the compressed file:

tar -xf vscode_cli.tar.gz
rm vscode_cli.tar.gz

You should have an executable file named code in the current directory. This step only needs to be completed once.

To ensure VS Code session is created without a strange error, it's best to remove ~/.vscode before calling the code executable in your VS Code server batch script. The following example batch script to reflect this. The only drawback is that you will have to go to github and authorize the session with the 8-character code every single time you start a VS Code session on the supercomputer.

Create a SLURM batch script that loads your preferred software environment and starts a VS Code tunnel on a compute node. In this example, the script is named test_vscode.sbatch:

nano test_vscode.sbatch

Paste the example batch script shown below into the file and modify it as needed for your account, partition, modules, and runtime requirements. The example script loads Python, removes any existing VS Code session data that could interfere with tunnel creation, redirects temporary files to scratch storage, and starts a VS Code tunnel using a unique tunnel name based on your username and compute node.

If your workflow requires additional modules or a Python virtual environment, load or activate them before the final code tunnel command.

This step only needs to be completed once.

Note: Replace yourusername within the chdir SLURM directive with your OSCER username.

#!/bin/bash

#SBATCH --partition=sooner_test
#SBATCH --container=el9hw
#SBATCH --output=vscode_%J_stdout.txt
#SBATCH --error=vscode_%J_stderr.txt
#SBATCH --chdir=/home/yourusername
#SBATCH --ntasks=1
#SBATCH --mem=2G
#SBATCH --time=1:00:00

# Load modules
module purge
module load Python/3.10.8-GCCcore-12.2.0

# Activate python virtual environment, if needed

# Remove ~/.vscode to ensure session can be started without error
rm -rf ~/.vscode
# Redirect /tmp to your scratch to avoid vscode failure
export TMPDIR=/scratch/$USER/tmp
mkdir -p $TMPDIR
export TUNNELNAME=$USER-$(hostname -s)
echo Tunnel Name: $TUNNELNAME
$HOME/code tunnel --accept-server-license-terms --name=$TUNNELNAME

Submit the batch script using sbatch:

sbatch test_vscode.sbatch

After submission, Slurm will return a message similar to:

Submitted batch job 15988858

The number shown is the job ID. Once the job starts running, it will launch VS Code Server on the assigned compute node and create a secure tunnel that can later be accessed from your local VS Code application. See here for more details regarding VS Code Remote Tunnels.

You can monitor the job's status by running:

watch squeue --job JOB_ID

When the job state changes to R (running), press Ctrl+C to stop monitoring.

The VS Code tunnel information will be written to the job's standard output file. You can monitor this file using:

tail -f vscode_JOBID_stdout.txt

After a minute or two, you should see a message instructing you to visit GitHub's device authorization page and enter an 8-character code. Open the URL shown in the output, sign in to GitHub if necessary, and enter the code to authorize the OSCER compute node.

After authorization is complete, the output file will eventually display a URL similar to:

https://vscode.dev/tunnel/username-node

The final portion of the URL (username-node in this example) is the tunnel name. Make note of this name, as you will use it when connecting from your local VS Code installation. You do not need to open the URL itself.

Return to VS Code on your local computer. Open the Command Palette by pressing Ctrl+Shift+P (or Cmd+Shift+P on macOS), then run the command:

Remote-Tunnels: Connect to Tunnel

The first time you use Remote Tunnels, VS Code may ask you to sign in to GitHub. After signing in, select the tunnel name identified in the previous step.

Once connected, the tunnel name will appear in the lower-left corner of the VS Code window, indicating that you are working on the remote OSCER compute node.

After connecting, open your project directory and begin working as you would in a local VS Code session. The first time you open a workspace, VS Code may ask whether you trust the files in that location.

For Python development, you may need to select a Python interpreter. For Jupyter notebooks, you may need to select an appropriate kernel. You may also need to install Python, Jupyter, or other extensions on the remote VS Code Server, even if those extensions are already installed on your local computer.

When you finish working, disconnect from the remote session by clicking the blue connection indicator in the lower-left corner of VS Code and selecting Close Remote Connection.

After disconnecting, open the Remote Explorer view, locate the tunnel, right-click it, and select Unregister Tunnel. This removes the tunnel registration and prevents future conflicts when creating a new tunnel with the same name.

Otherwise you'll encounter an error like this next time you want to start the tunnel again with your batch script:

error Could not create tunnel with name: username-node
Reason: tunnel name already in use

Finally, terminate the VS Code Server job on OSCER:

scancel JOB_ID

For example:

scancel 15988858

This releases the compute resources that were allocated to the VS Code session.

1. Log in to Sooner (Step 4).
2. Submit your existing batch script (Step 7).
3. Authorize the tunnel when prompted (Step 8).
4. Connect to the tunnel from VS Code (Step 10).
5. When finished:
   1. Close the remote connection (Step 12).
   2. Unregister the tunnel (Step 12).
   3. Cancel the SLURM job (Step 13).

You do not need to repeat

• VS Code Installation (Step 1)
• Remote-Tunnels Installation (Step 2)
• GitHub acount creation (Step 3)
• VS Code CLI download (Step 5)
• Batch script creation (Step 6)

Error after upgrading/downgrading VS Code CLI

If you experience unexpected issues after upgrading or downgrading the VS Code CLI in your home directory, run the following command:

rm -rf ~/.vscode ~/.vscode-server ~/.vscode-R

This removes the ~/.vscode directory and resets your local VS Code configuration. After doing so, you will need to reauthenticate your tunnel using the 8-character code described in Step 8.

Exceeding Time Limit of VS Code Server Job

If your VS Code Server batch job is terminated due to the time limit, you will need to repeat the session setup process. First, close the active tunnel connection and unregister it as described in Step 12. After that, resubmit the VS Code Server batch job and continue through Steps 7 to 11: monitor the job output, reauthorize the tunnel if prompted, reconnect from VS Code, and resume coding or debugging.

Plotting with R Failed due to X11 Forwarding Error

If you use VS Code to run R instead of Python and encounter an X11 forwarding error when generating plots or images, you will need to adjust your workflow. In this case, close the VS Code interface on your local machine, install the required R packages on OSCER, and run your R code through a Jupyter session within VS Code.

First, log in to your OSCER account if you have not already done so. If you are using R via Conda (Miniconda/Anaconda), activate your Conda environment as needed. Otherwise, load the appropriate R module. For example, to load R 4.2.1, run:

module load R/4.4.2-gfbf-2024a 

Start an interactive R session by typing:

R

Within the R console, install the required packages by running the following commands:

install.packages('languageserver', repos='https://cran.r-project.org/')
install.packages('IRkernel', repos='https://cran.r-project.org/')
IRkernel::installspec()

These packages enable VS Code to recognize and use R within Jupyter notebooks. After installation, exit the R console by pressing Ctrl+D (or Command+D on macOS).

If your VS Code server batch script was not originally configured for R, ensure that the R module is loaded within the script. An example configuration for an R-enabled VS Code Server batch script is shown below:

#!/bin/bash

#SBATCH --partition=sooner_test
#SBATCH --container=el9hw
#SBATCH --output=vscode_%J_stdout.txt
#SBATCH --error=vscode_%J_stderr.txt
#SBATCH --chdir=/home/yourusername
#SBATCH --ntasks=1
#SBATCH --mem=4G
#SBATCH --time=1:00:00

# Load modules
module purge
module load R/4.2.1-foss-2022a

# Activate R virtual environment, if needed

# Remove ~/.vscode to ensure session can be started without error
rm -rf ~/.vscode

# Redirect /tmp to your scratch to avoid vscode failure
export TMPDIR=/scratch/$USER/tmp
mkdir -p $TMPDIR
export TUNNELNAME=$USER-$(hostname -s)
echo Tunnel Name: $TUNNELNAME
$HOME/code tunnel --accept-server-license-terms --name=$TUNNELNAME

Replace yourusername with your OSCER username.

After submitting the VS Code server job, open VS Code on your local computer and connect to the remote tunnel. To avoid X11 forwarding issues when plotting in R, run your code inside a VS Code Jupyter session rather than a standard R terminal session.

After connecting to the tunnel, open the Command Palette using Ctrl+Shift+P (or Cmd+Shift+P on macOS), then type:

Create: New Jupyter Notebook

and select it. By default, the notebook will start in Python. Click the language/kernel selector and change it to R.

Next, select the correct R kernel for the notebook by choosing the kernel selection option (top-right area of the interface) and selecting the available R kernel (Jupyter kernel linked to your R installation).

Once the R kernel is active, you can paste and execute R code directly in notebook cells. Plots and outputs will render within VS Code without requiring X11 forwarding.

If the Jupyter extension is not installed, open the Extensions panel in VS Code after connecting to the remote tunnel, search for Jupyter, and install it.