Using VS Code’s Remote Tunnels extension¶

This page contains information on how to leverage VS Code’s built-in Remote Tunnels extension on Baskerville. This allows you to run VS Code locally to debug the code you are running on Baskerville.

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 please 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 Baskerville.

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

Process Overview¶

Install the VS Code application 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.
  
  Please be considerate of other users when requesting resources for your session. There is potential for Remote Tunnel jobs to be underutilised whilst still consuming Baskerville resource.
- Add module load commands as necessary, for example loading a specific Python version.
Tail (tail -f) 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 (see here), 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 Baskerville resources are freed for use by other jobs.

Example Batch Script¶

The following script will perform the following actions:

Start a job on a Baskerville compute node.
Check whether the VS Code CLI binary is available, downloading it if necessary.
Run 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 baskerville

# 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. Note that these versions will accumulate over time so we recommend periodically deleting this directory to ensure that only the versions you are currently using reside there.

Exclude paths from file watching¶

VS Code uses a file watcher to monitor when files are created, modified or deleted from your home directory. For a shared filesystem like Baskerville, this task can become resource-intensive if there are a lot of files. Use the files.watcherExclude setting in VS Code to specify the paths you would like 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 tunnels are secured, see: https://code.visualstudio.com/docs/remote/tunnels#_how-are-tunnels-secured