Preparations

SSH Keys

The best way to connect to the through the cluster with VSCode is by using ssh keys. If you do not yet use ssh keys on the cluster, we recommend that first change your general connection the cluster to using ssh keys (see How to login to ALICE or SHARK ).

If you have already been using ssh keys to connect to ALICE, you can in principle use your existing ssh key or create a new one specific for using with VSCode.

SSH config

You should set up a separate ssh config file for VSCode, because VScode wants to have write access to the ssh config if you use the manual setup. In order to avoid accidentally overwriting anything else in your ssh config, it is best to use a separate ssh config.

We would recommend setting up the ssh config for VSCode in advance because this is easier when working with an ssh gateway

First, we create a separate ssh directory to put the config file. Open a terminal on your Linux or MacOS computer or open PowerShell if you are on Windows and run:

Next, create a file config in the new directory. For simplicity, we can just open the file in VSCode from the command line (also PowerShell)

Of course, you can use any other editor of your choice.

Now that the file is open, add host settings for at least one login node similar to what you have already done in your standard ssh config based on Login to ALICE or SHARK from Linux :

Set up VSCode

First, you need to install an extension. Open VSCode and go to Extensions. Then search for the extension “Remote - SSH” ( https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh ) and install it.

After it was installed and activated, go to “Preferences -> Settings” and search for “remote.ssh”.

In the list of settings that has appeared, look for “Remote.SSH: Config File” (probably the first one in the list) and specify the full path to your ssh config, e.g., /home/<username>/.ssh_vscode/config (Linux) or C:\Users\<username>\.ssh_vscode\config (Windows) where “<username>” is your user name on your local workstation.

It is best to verify that VSCode can find your ssh config. Type either “F1” or go to “Help → Show All Commands” and type in “Remote-SSH: Open SSH Configuration File”. After hitting enter, it should show you a drop-down menu with the path to the ssh config that you just specified. When you click on it, it should open the file.

Connecting with VSCode

When the config file is set up correctly, you can type “F1” or go to “Help → Show All Commands” and search for “Remote-SSH: Connect to Host”. This should show you the host alias for VSCode that you have defined in your ssh config (e.g., “alice2vsc” or “shark2vsc”) as an option. If it does, hit enter and wait. VSCode will probably open a new window and initialize. This takes a few seconds and then it should show you in the bottom right corner that you are connected.

You can open folders on the cluster just like you would on your local workstation. If you open a git repository, then you can use the git workflow in VSCode.

Your local VSCode will remember that opened a folder on the cluster which allows you to quickly reconnect.

Using Jupyter notebooks with VSCode

It is possible run Jupyter notebooks directly in VSCode. This only requires a few additional steps for which we assume that you have already set up VSCode with the instructions above.

In order to get Jupyter notebooks to work in VSCode, you need to do the following:

1. Set up a Slurm job script for running a Jupyter notebook as described here Running Jupyter notebooks in an interactive session

2. Add the host alice-notebook or shark-notebook as outlined in Running Jupyter notebooks in an interactive session | Accessing the Jupyter notebook on your local workstation to the ssh config file for VSCode (~/.ssh_vscode/config). If you set up separate keys for VSCode as described above, also add the line IdentityFile ~/path/to/private/ssh/key to the host settings.

3. Submit the Slurm job script from step 1.

4. Check the Slurm output file an retrieve the name of the node and port. Adjust the host settings for alice-notebook or shark-notebook in the ssh config file accordingly. You will also need the URL from the Slurm output script, not the one starting with 127.0.0.1, but the other one.

5. Go to Remote Explorer or run “Remote-SSH Connect to Host” and select the host name (alice-notebook or shark-notebook). It might take a few seconds for the VSCode server to connect. You can check the lower-left corner which should read SSH: alice-notebook or SSH: shark-notebook once it connected. You will still need to connect to the Jupyter notebook server in the next steps

6. Open a .ipynb file and in the top-right corner choose “Python Kernel”: First, choose “Select Another Kernel”, then “Existing Jupyter Server”.

7. You will be asked for the URL to the server. From the Slurm output script, copy the URL (not the one starting with 127.0.0.1) in the input field and the password

8. After that select the Python kernel if needed. If everything is setup correctly, you will see the Python kernel in the top right corner and you can run the Jupyter notebook.