Using Visual Studio Code's Remote Tunnels extension¶

This page contains information on how to use Visual Studio Code's built-in Remote Tunnels extension on BlueBEAR. This allows you to run Visual Studio Code (VS Code) locally to debug the code you are running on BlueBEAR.

This method is better than using the Remote SSH extension, which runs the VS Code server on a login node where the server process may be de-prioritised and killed by the system if it consumes too much resource. The Remote Tunnels extension runs the VS Code server on a compute node, which is more suitable for this purpose.

GitHub account required

This process requires that you connect VS Code with a GitHub account. If you don't already have a GitHub account then create one here: https://github.com/signup

The VS Code Remote Tunnels extension lets you connect to a remote machine via a secure tunnel. The following information outlines the process for leveraging this facility for use on BlueBEAR.

Note that these docs paraphrase sections of the official Remote Tunnels documentation – for further details see the information in the following URL: https://code.visualstudio.com/docs/remote/tunnels

Process overview¶

Install the VS Code software app on your local machine, if you don't already have it.
Install the VS Code Remote Tunnels extension.
Connect VS Code to your GitHub account.
Submit a batch job using the example below. Note that you may want to:
- Adjust the #SBATCH headers for the resource that you require.
  
  Don't under-utilise BlueBEAR resources
  
  Please be considerate of other users when requesting resources for your session. There is potential for Remote Tunnel jobs to be under-utilised whilst still consuming BlueBEAR resource.
- Add module load commands as necessary, for example loading a specific Python version.
Follow the output (using tail -f) of the slurm.out file generated by the batch job (see here for more info). Follow the link to authenticate VS Code via GitHub, pasting the given code as required.

Tip

You can copy the whole code, e.g. AAAA-BBBB as written and paste it directly into the first of the boxes on the GitHub Device Activation page (https://github.com/login/device) - there is no need to paste or type the characters individually.
Once the tunnel is active you can connect using your local VS Code's Remote Tunnels extension. Please refer to the following documentation for further info: https://code.visualstudio.com/docs/remote/tunnels#_remote-tunnels-extension

Browser Access to remote server

It's also possible to connect to the remote instance in a browser, using link given in the slurm.out file, e.g. https://vscode.dev/tunnel/some-randomly-assigned-tunnel-name
Cancel your job, using scancel, after you have finished using the Remote Tunnel.

Idle resources

You must cancel you job once you have finished using the tunnel. This is so that the BlueBEAR resources are freed for use by other jobs.

Example batch script¶

The script below performs the following actions:

Starts a job on a BlueBEAR compute node.
Checks whether the VS Code CLI binary is available, downloading it if necessary.
Runs the VS Code Remote Tunnel, passing --accept-server-license-terms.

tunnel_job.sh

#!/bin/bash

#SBATCH --ntasks 8
#SBATCH --nodes 1
#SBATCH --time 0-1  # run for 1 hour
#SBATCH --account _projectaccount_
#SBATCH --qos _userqos_

set -e

module purge; module load bluebear

# add any required module loads here, e.g. a specific Python

CLI_PATH="${HOME}/vscode_cli"

# Install the VS Code CLI command if it doesn't exist
if [[ ! -e ${CLI_PATH}/code ]]; then
    echo "Downloading and installing the VS Code CLI command"
    mkdir -p "${HOME}/vscode_cli"
    pushd "${HOME}/vscode_cli"
    # Process from: https://code.visualstudio.com/docs/remote/tunnels#_using-the-code-cli
    curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli.tar.gz
    # unpack the code binary file
    tar -xf vscode_cli.tar.gz
    # clean-up
    rm vscode_cli.tar.gz
    popd
fi

# run the code tunnel command and accept the licence
${CLI_PATH}/code tunnel --accept-server-license-terms

Additional information¶

Data in your home directory¶

The VS Code CLI (i.e. the remote end of the tunnel) stores its data in the following directory: ${HOME}/.vscode-cli

This directory in turn contains subdirectories (located in ${HOME}/.vscode-cli/server-stable/bin), for each of the local VS Code versions from which you connect. These versions accumulate over time so you may want to periodically delete the contents of this directory to ensure that only the versions you are currently using are stored.

Exclude paths from the file watcher¶

VS Code uses a file watcher to monitor when files are created, modified, or deleted from your home directory. For a shared filesystem (such as the RDS on BlueBEAR), this task can become resource-intensive if there are many files. Use the files.watcherExclude setting in VS Code to specify the paths you want to remove from automatically indexing (there is no need to exclude symlinks from your home folder). See here for background and here for a VS Code settings example that contains files.watcherExclude.

Remote Tunnel Security

For info on how the security of tunnels is handled, see: https://code.visualstudio.com/docs/remote/tunnels#_how-are-tunnels-secured