VSCode in IRB Cluster¶
VPN Required
For any case, you need to activate the VPN.
Description¶
These are the instructions to use Visual Studio Code to run and debug scripts/notebooks within the IRB cluster. Three approaches are documented:
- Login Node: For non-computationally expensive tasks
- Interactive Node – Method A (Dynamic Node): For computationally expensive tasks with flexible resource allocation
- Interactive Node – Method B (Fixed Node): For computationally expensive tasks, always connecting to the same node
Not Computationally Expensive Tasks - Login Node¶
- Open VSCode in your local computer
- On the sidebar, click the icon that looks like a screen
- Click on the option that says
irbcluster02, either the right arrow (open in current window) or the other icon (new window).
Computationally Expensive Tasks - Interactive Node¶
Both methods below run VSCode connected to a compute node via SSH. Choose based on your workflow:
- Method A (Dynamic Node): Allocates a new node each time via the
interactivecommand. Better for one-off jobs with flexible resource needs. - Method B (Fixed Node): Always submits to the same node via
sbatch. Better for ongoing work where you want to preserve your VSCode session history (recently opened files, workspace state).
When to use Method A
Use this method when you need flexible resources or a different node each time. Keep in mind that every time you are allocated a different node, VSCode will not remember your previously opened files and folders for that session.
Step 1: [CLUSTER] Open interactive session¶
Existing screen session
If you already have a screen session opened in the cluster with the interactive session, go directly to step 4.
The first step is to allocate the resources you will need for your executions.
We can do this with the interactive command.
Tip: Use screen
Consider launching the interactive session in a screen so that it doesn't get killed when the terminal is closed.
Launch an interactive session within a given node, allocating some computing resources:
Then, check on which node you are. You can look at the prompt, or use the hostname command.
Example:
Step 2: [CLUSTER] Execute job vscode-interactive-job.sh¶
First time setup
If it is the first time you are using this method, copy the following lines into a
file called vscode-interactive-job.sh in your home directory.
File: vscode-interactive-job.sh
Execute the vscode-interactive-job.sh script with:
id_ecdsa not found
If you get an error saying that the file id_ecdsa is not found, you can generate it with:
It will prompt you several times to confirm the generation of the key. You can just press Enter to accept the default values.
The terminal will look like it got stuck, but what is happening is that it is waiting for the SSH tunnel to be established.
Step 3: [LOCAL] [ONE-TIME-STEP] Add the SSH configuration¶
Modify the file ~/.ssh/config in your local machine to include the following configuration:
Example:
Node change
This is marked as a "ONE-TIME-STEP", but in reality it depends on the node you are allocated. If you need to change the node or add a new node, the configuration will need to be updated.
Tip (Optional): Helper function to add SSH configuration
Here is a helper function that you can add to your .bashrc file to make it easier to
setup the node and the tunnel.
Steps the function does:
- Prompts only for the host alias.
- Checks if a config entry for that host already exists in
~/.ssh/config(and skips adding it if so). - Uses the fixed configuration values (with HostName as "%h", the fixed ProxyJump, port 22, and the current computer user).
- Computes the full hostname for the tunnel (by appending ".hpc.irbbarcelona.pcb.ub.es" to the alias) and creates the SSH tunnel (running in the background).
add_cluster_ssh_host_with_tunnel() {
read -p "Enter host alias (e.g., irbccn39): " host_alias
current_user=$(whoami)
# Check if SSH config for this host already exists
if grep -qE "^Host[[:space:]]+${host_alias}\$" ~/.ssh/config; then
echo "SSH configuration for host '${host_alias}' already exists. Skipping configuration update."
else
new_entry="Host ${host_alias}
HostName %h
ProxyJump irblogin02.sc.irbbarcelona.org
User ${current_user}
Port 22
"
echo -e "\n${new_entry}" >> ~/.ssh/config
echo "SSH configuration added for host '${host_alias}'."
fi
# Create the SSH tunnel.
# Assuming the full hostname is <host_alias>.hpc.irbbarcelona.pcb.ub.es
computed_hostname="${host_alias}.hpc.irbbarcelona.pcb.ub.es"
tunnel_cmd="ssh -f -N -L 2222:${computed_hostname}:22 ${current_user}@irblogin02.sc.irbbarcelona.org"
echo "Establishing SSH tunnel with command:"
echo "${tunnel_cmd}"
eval ${tunnel_cmd}
if [ $? -eq 0 ]; then
echo "SSH tunnel established for host '${host_alias}'."
else
echo "Failed to establish SSH tunnel."
fi
}
alias addsshcluster='add_cluster_ssh_host_with_tunnel'
Step 3.1: [LOCAL] [ONE-TIME-STEP] Access through the terminal to the node¶
To make sure the configuration is working, access the node through the terminal with:
Example:
This is needed the first time you connect to a new node, so that the node is added to the known hosts.
Step 4: [VSCODE] Connect VSCode to the interactive node¶
Open Visual Studio Code and make sure you have installed the Remote - SSH extension.
Open the side bar at the "Remote - SSH" panel, and then click the irbccn* option (e.g., irbccn39), either the right
arrow (open in current window) or the other icon (new window). A new window will open with the
terminal connected to the interactive node. All the execution of notebooks and debuggers will be done from this node.
Connection retry
You might have to click Retry a few times, as sometimes it doesn't connect at the first try.
Tip: Create a 'Profile' to keep the VSCode settings and extensions
You can create a profile in VSCode to keep the settings and extensions for the connection to the cluster. This works similar to the idea of conda environments, but for the VSCode settings.
To create a profile, click on the gear icon in the bottom left corner of VSCode, and then click on Profiles and create a new profile.
[OPTIONAL] Open SSH tunnel — only if the connection from VSCode doesn't work¶
If VSCode connection fails
If opening VSCode on the local computer and trying to connect to the cluster doesn't work, run the following command in a new terminal on your local machine:
Example:
Replace <interactive_hostname> with your allocated node (e.g., irbccn39.hpc.irbbarcelona.pcb.ub.es) and <user> with your username.
When to use Method B
Use this method when you want to always connect to the same node, preserving your VSCode
session history (recently opened files, workspace state). It also requires fewer steps since
the job is submitted directly from the login node — no screen or interactive session needed.
Step 1: [ONE-TIME-STEP] Create the SBATCH script¶
Create the directory if it doesn't exist:
Then create the file ~/.local/bin/vscode-it with the following content:
File: ~/.local/bin/vscode-it
#!/bin/bash
#SBATCH --job-name="code-client"
#SBATCH --cpus-per-task=4
#SBATCH --nodelist=<IBCLUSTER_NODE>
#SBATCH --partition=bbg_cpu_zen4
#SBATCH --mem=16G
#SBATCH --qos=interactive
#SBATCH --time=7-00:00:00 # walltime
set -xe
/usr/sbin/sshd -D -p 2222 -f /dev/null -h ${HOME}/.ssh/id_ecdsa
Adjust resources to your needs
Edit --nodelist, --cpus-per-task, --mem, and --partition to match the node and
resources you want to reserve. The --nodelist value pins the job to a specific node —
this is the key feature of this method.
id_ecdsa not found
If you get an error saying that the file id_ecdsa is not found, you can generate it with:
It will prompt you several times to confirm the generation of the key. You can just press Enter to accept the default values.
Step 2: [CLUSTER] Submit the job from the login node¶
From the IRB cluster login node, run:
The job will be submitted to the SLURM queue and start running on the node specified in --nodelist.
You can verify it is running with:
Step 3: [LOCAL] [ONE-TIME-STEP] Add the SSH configuration¶
Modify the file ~/.ssh/config in your local machine to include the following configuration:
Example (using the same node as the --nodelist in the script):
Fixed node advantage
Since this method always targets the same node, you only need to set up this configuration once and it will continue to work across all future sessions.
Step 3.1: [LOCAL] [ONE-TIME-STEP] Access through the terminal to the node¶
To make sure the configuration is working, access the node through the terminal with:
Example:
This is needed the first time you connect to the node, so that the node is added to the known hosts.
Step 4: [VSCODE] Connect VSCode to the node¶
Open Visual Studio Code and make sure you have installed the Remote - SSH extension.
Open the side bar at the "Remote - SSH" panel, and then click the irbccn* option (e.g., irbccn25), either the right
arrow (open in current window) or the other icon (new window). A new window will open with the
terminal connected to the node. All the execution of notebooks and debuggers will be done from this node.
Connection retry
You might have to click Retry a few times, as sometimes it doesn't connect at the first try.
Tip: Create a 'Profile' to keep the VSCode settings and extensions
You can create a profile in VSCode to keep the settings and extensions for the connection to the cluster. This works similar to the idea of conda environments, but for the VSCode settings.
To create a profile, click on the gear icon in the bottom left corner of VSCode, and then click on Profiles and create a new profile.
From Browser (code-server)¶
This approach doesn't use the VSCode app, but instead uses the code-server package to run a VSCode instance in the cluster. This will result in launching VSCode from the browser.
Description
The macgiver way of mounting the bbgcluster filesystem in our respective local computers is very inefficient when it comes to coding with VSCode, particularly with regards to git version control capabilities.
But there is a way to use full-fledged capabilities of VSCode for projects that are kept in the bbgcluster.
TL;DR
- Launch a vscode server in the bbgcluster.
- SSH tunnel to this session from a local terminal.
- Connect to the server using a browser.
- Do so while keeping everything secure.
Setting all up
For the time being this tutorial does not cover the set up part in depth. However, here there is a bundle of command lines that are needed for setting up the security part.
Become a certificate authority
# Generate private key
openssl genrsa -des3 -out myCA.key 2048
# Generate root certificate
openssl req -x509 -new -nodes -key myCA.key -sha256 -days 825 -out myCA.pem
Create CA-signed certs
NAME=vscode # Use your own domain name
# Generate a private key
openssl genrsa -out $NAME.key 2048
# Create a certificate-signing request
openssl req -new -key $NAME.key -out $NAME.csr
# Create a config file for the extensions
>$NAME.ext cat <<-EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = $NAME # Be sure to include the domain name here because Common Name is not so commonly honoured by itself
DNS.2 = bar.$NAME # Optionally, add additional domains (I've added a subdomain here)
IP.1 = 0.0.0.0 # Optionally, add an IP address (if the connection which you have planned requires it)
EOF
# Create the signed certificate
openssl x509 -req -in $NAME.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial \
-out $NAME.crt -days 825 -sha256 -extfile $NAME.ext
VSCode server in the bbgcluster
Screen
In the bbgcluster, either create
or access an existing vscode screen
Warning
When opening a new screen, this should be done from the login01 node, since this guarantees that the screen will be constantly running and not shut down (which could happen if the screen is opened in one of the other nodes).
Interactive
Launch an interactive session within a given node, allocating some computing resources:
Conda activate vsc_node environment
Warning
the environment vsc_node is supposed to have been already created by the user; check this reference.
Launch vscode server
From your bbgcluster home do:
unset XDG_RUNTIME_DIR && \
code-server --port 8090 \
--bind-addr 0.0.0.0 \
--cert vscode.crt \
--cert-key vscode.key
Warning
--cert file vscode.crt --cert-key file vscode.key are supposed to be already generated by the user.
SSH tunnel
In a terminal of your local computer, do the following:
Warning
htop is just a dirty trick to ensure the SSH tunnel does not spontaneouly shut down.
Connect to the server
Type the following https address in the browser:
A password prompt will appear. Fullfill the password request with a password you must have generated during the security setup referred to above.
Requirements
- Conda or Mamba installed
- Have an account on ngrok
Create a conda environment
The conda environment must include the packages code-server, pyngrok and screen
Run code server in a screen (inside login01)
Right after creating the screen, create an interactive session and remember on which node you are allocated.
Exit the screen with Ctrl + A + D
Run a Ngrok tunnel in a screen (inside login01)
Note
If this is your first time doing this step, you'll first need to setup your authentication token for ngrok.
- Log in to your ngrok home page.
- On the left-hand side bar:
Getting Started > Your Authtoken - On the
Command Linesection, copy only the key, which is the big string with random letters and numbers. -
Go back to the terminanl in the cluster (with the
vsc_pyngrokenvironment activated) and add your authentication token with the following command:ngrok authtoken <the_token_you_copied_in_the_previous_step>
This setup only has to be done once.
Copy the URL to your browser and exit the session Ctrl + A + D
Check your VSCode password
Browse your VSCode remotely
When entering the URL in your browser, click Visit site and introduce the password you obtained in the previous step in order to be able to use VSCode.
Reference¶
- Carlos López-Elorduy
- Federica Brando
- Ferriol Calvet
- Ferran Muiños
- Jordi Deu Pons