Using VSCode with the Hub#

Pre-requisites#

⭐ LEAP Pangeo Access

You must have the ability to start a server on LEAP Pangeo. More information about membership can be found in the Membership page.

⭐ Websocat

websocat must be installed on the client machine. pip install websocat works on Mac OS, and pre-built binaries are available for all other operating systems.

⭐ VSCode

VSCode must be installed on the client machine.

⭐ VSCode Extensions

Find and install the Remote-SSH and Jupyter extensions on the VSCode Extensions Marketplace.

Image Image

Remote-SSH will be used to connect to your LEAP Pangeo server, while the Jupyter extension will be used to open .ipynb notebooks and manage the kernel that runs your code on the remote server.

Before you begin

There are two levels of authentication – your JupyterHub token and your SSH key pair (public/private). This guide will walk you through both so you can connect with JupyterHub from your VSCode without entering a password.

The JupyterHub token is like a temporary password that lets your local machine talk to the JupyterHub server over a special channel (via websocat).

The JupyterHub token will be included in your ~/.ssh/config file on your local machine so ssh knows how to talk to the server.

Your SSH key pair is like a secure ID card. Your local machine holds the private key (secret), and the server holds your public key (the badge that proves it trusts you).

The SSH public key will be added to your GitHub account for convenience, and then downloaded onto the JupyterHub server (saved into ~/.ssh/authorized_keys) so the server knows your local machine is trusted.

1 [Web Browser] Start your server#

This setup only works after you start your JupyterHub server. So, start your server! Please keep in mind that even after setting up Remote-SSH on your VSCode, you would have to start your server on LEAP Pangeo before attempting to connect to the server.

2 JupyterHub Token Setup#

2-1 [Web Browser] Obtain a JupyterHub Token#

We will need to create a JupyterHub token for authentication.

  1. Go to the JupyterHub control panel. You can access it via File -> Hub control panel in JupyterLab, or directly going to https://leap.2i2c.cloud/hub/token.

  2. In the top bar, select Token.

  3. Create a new Token, and keep it safe. Treat this like you would treat a password to your JupyterHub instance! It is recommended you set an expiry date for this.

2-1 [Local Terminal] Configure local ~/.ssh/config with the JupyterHub Token#

We will set up our ssh config file to tell ssh how to connect to our JupyterHub. Add an entry that looks like this to the end of your ~/.ssh/config file (create it if it does not exist).

Host leap.2i2c.cloud
    User jovyan
    ProxyCommand websocat --binary -H='Authorization: token <YOUR-JUPYTERHUB-TOKEN>' asyncstdio: wss://%h/user/<YOUR-JUPYTERHUB-USERNAME>/sshd/

replace:

  • <YOUR-JUPYTERHUB-TOKEN> with the token you generated earlier

  • <YOUR-JUPYTERHUB-USERNAME> with your jupyterhub username

3 SSH Key Pair Setup#

3-1 [Local Terminal] Generate a ssh key pair#

  1. Generate the key pair on local terminal by executing the command:

    ssh-keygen -t ed25519 -C "your_email@example.com" Make sure to replace your_email@example.com with your actual email address.

  2. Add key to ssh-agent by executing: eval "$(ssh-agent -s)" and

    ssh-add  #~/.ssh/id_ed25519

  3. Copy the public key: Use following command to show the public key on your local machine: cat ~/.ssh/id_ed25519.pub And copy the entire key, including the email address.

    Do not expose your private key id_ed25519 - the private key should not be shared.

3-2 [Web Browser] Save the public key on Github#

  1. Go to Github key settings, then click on “New SSH Key.”

  2. Paste the copied public key (including email address) into the “Key” box, and save. In the next step, we will leverage Github to save your public key on JupyterHub.

3-3 [Web Browser] Setup ssh keys on your JupyterHub server#

  1. Make sure your JupyterHub server is still running. If not, start a new one.

  2. Open a terminal in JupyterLab on your web browser

  3. Run the following commands:

    mkdir -p ~/.ssh
wget https://github.com/<YOUR-GITHUB-USERNAME>.keys -O ~/.ssh/authorized_keys
chmod 0600 ~/.ssh/authorized_keys

    replacing <YOUR-GITHUB-USERNAME> with your github username.

  4. Verify that authorized_keys contains your key by running cat ~/.ssh/authorized_keys on the JupyterLab Terminal

  5. If it is empty or nonexistent, then create the file authorized_keys in the ~/.ssh/ directory and paste your ssh public key (cat ~/.ssh/id_ed25519.pub, from local terminal) and save file.

With that, we are ready to go!

4 [Local Terminal] Try ssh-ing into your JupyterHub!#

After all this is setup, you’re now able to ssh in! On your local terminal, try:

ssh leap.2i2c.cloud

and it should just work! If configured correctly, leap.2i2c.cloud should not ask you for a password.

Attention

Debugging Help

If you get the error ssh: connect to host leap.2i2c.cloud port 22: Operation timed out, then check you have installed websocat by running run pip install websocat and confirm that ther config file in the correct directory, ~/.ssh/config

If the CLI asks for a password, please verify that your access token and public keys are valid and consistent across platforms and try the previous steps again. Keep in mind this test has to only work once, and it is not necessary to ssh into JupyterHub via CLI once you confirm this works once.

5 [VSCode] Connect to LEAP Pangeo on VSCode#

Launch VSCode, click on the top search bar to open the Command Palette (cmd + shift + P on Mac)

  1. Enter >Remote-SSH: Add New SSh Host

Image

  1. Enter ssh leap.2i2c.cloud

Image

  1. Click on the first option, /Users/<your_local_username>/.ssh/config

Image

  1. Follow further prompts until you are connected. You should see this on your top bar once you are connected.

Image

  1. Click on “Open Folder” and select the home directory. You should be able to access your LEAP-Pangeo Notebooks remotely now.

Image

6 [VSCode] Write / execute your code via a remote kernel#

  1. Once you open a Notebook, you will find a selection menu for a kernel on the top-right.

Image

  1. Select the option “Python Environments”

Image

  1. Selected the recommended conda (Python 3.x.x) kernel

Image

You should now be good to execute code via remote kernel on the LEAP server from local VSCode!

7 [VSCode] Re-connecting to Remote SSH After Setup#

  1. Type >Remote-SSH: Connect to Host into the top search bar.

Image

  1. Select leap.2i2c.cloud. Keep in mind this action will only work if the 2i2c Server is already active.

Image

  1. Repeat the steps from “Write / execute your code via a remote kernel”

Contributors to this documentation:

  1. Yuvi [yuvipanda], jupyter-sshd-proxy:

  2. Joe Ko [jk4730@columbia.edu], clarifications on how to setup the local public key

  3. Sungjoon Park [sp4050@columbia.edu], whom you can contact for questions regarding this workflow