Skip to content

3. Remote Dev Environment Setup.md

Latest commit

 

History

History
222 lines (144 loc) · 10.4 KB

3. Remote Dev Environment Setup.md

File metadata and controls

222 lines (144 loc) · 10.4 KB

Remote Development Environment Setup Tutorial

This tutorial will guide you through setting up a remote development environment, where you will securely connect to a remote host from your local machine. Follow these steps to configure both the host and your local environment.

This tutorial was inspired by this page of the VS Code Documentation.

0. Introduction to SSH keys

SSH (Secure Shell) keys are a pair of cryptographic keys used to authenticate and securely connect to remote servers or systems. Rather than using a password, SSH keys offer a more secure and convenient way to log into servers.

An SSH key pair consists of two parts:

  1. Private Key: This stays on your local machine and should be kept secret. It's used to prove your identity when connecting to remote systems.
  2. Public Key: This can be shared openly. You place this on any server you want to access. The server uses it to verify that the private key you use matches the public key it has.

When you attempt to connect to a server, the server challenges your client to prove it holds the correct private key (without actually sending it). If your client can prove it without revealing the key itself, the connection is successful, and you’re granted access.

Why use SSH keys?

  • They are more secure than using passwords, especially against brute force attacks.
  • They are convenient because you don’t need to type a password every time you log in.
  • They can be encrypted with a passphrase for additional security.

Essentially, SSH keys are like a digital ID card that allows you to prove your identity when logging into remote systems.

1. Setting Up the Remote Host

⚠️ This step is typically done by the host administrator, so you can skip this if you're not the admin.

To allow your local machine to connect to the remote host, you need to create a new user account on the remote host and set a password for them.

Before proceeding, ensure the SSH server is installed on the host machine (typically openssh-server on Linux). You'll also need to temporarily adjust some SSH configuration settings to allow the key transfer.

  1. Setup SSH Server: If not already installed, install and start the SSH server. For example in Ubuntu:

    sudo apt install openssh-server # Install OpenSSH Server
sudo systemctl start ssh        # Start SSH service
sudo systemctl enable ssh       # (Optionnal) Enable SSH to start on boot
sudo ufw allow ssh              # (Optionnal) Allow SSH through firewall

  2. Configure SSH Settings:

    • Temporarily modify the /etc/ssh/sshd_config file to set the PasswordAuthentication variable to yes and the ChallengeResponseAuthentication variable to no. This step is necessary for the initial key transfer.
    • After completing the key transfer, you should revert these changes to enhance security.

  3. Add a new user and set a password on the remote host:

    sudo useradd -s /bin/bash -m username
sudo passwd username

    Replace username with the username you wish to create on the host.

2. Test the Connection

⚠️ You can start here

Before proceeding with the SSH key setup, you should verify that your local machine can reach the remote host. Try pinging the host to check the connection:

ping hostname

If the ping fails, check the following:

  • Ensure your local machine and the host are on the same network or VPN (if applicable).
  • Make sure the host machine is powered on and properly connected to the network.
  • Verify the host's firewall settings and ensure that port 22 (SSH) is open.

3. Setup your SSH keys

Now, let's generate an SSH key pair on your local machine. This will allow secure authentication without the need to type a password.

Once the key pair is created, you need to add your public key to the remote host's ~/.ssh/authorized_keys file to allow passwordless SSH login.

⚠️ Warning:

If you're on Windows with WSL (Windows Subsystem for Linux), the commands below need to be run in the native PowerShell, not inside the WSL terminal!

Windows (using PowerShell):

  1. Generate a pair of SSH keys:

    ssh-keygen -t ed25519 -b 4096

    If prompted, accept the default location for the key (~/.ssh/id_ed25519) by typing Enter.

  2. Use icacls to grant read permissions to your private key:

    icacls "~/.ssh/id_ed25519" /grant <username>:R

    Replace <username> with your Windows username.

  3. Set up the SSH connection by appending the public key to the remote user's authorized_keys file:

    $USER_AT_HOST="your-user-name-on-host@hostname"
$PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
$pubKey=(Get-Content "$PUBKEYPATH" | Out-String); ssh "$USER_AT_HOST" "mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo '${pubKey}' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

    Make sure to replace your-user-name-on-host with the correct username and hostname with the host's address!

Linux/MacOS:

  1. Generate a pair of SSH keys:

    ssh-keygen -t ed25519 -b 4096

    When prompted, accept the default location for the key (~/.ssh/id_ed25519) by typing Enter.

  2. Set proper permissions on your private key:

    chmod 400 ~/.ssh/id_ed25519

  3. Use ssh-copy-id to automatically copy the public key to the remote host's authorized_keys file:

    export USER_AT_HOST="your-user-name-on-host@hostname"
export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
ssh-copy-id -i "$PUBKEYPATH" "$USER_AT_HOST"

    Make sure to replace your-user-name-on-host and hostname with the appropriate values!

4. Check your ssh keys setup

If you made everything correctly so far, you should be able to connect to the remote host using ssh without being ask to type your password

ssh your-user-name-on-host@hostname

Remember that you can always close the connexion and return to your local shell using the exit command.

5. Change your SSH configuration

To simplify your SSH login process even further, you can configure your SSH settings by adding an entry to the ~/.ssh/config file on your local machine. This step is optional, but it will make it easier to connect to your remote host in the future.

⚠️ Warning:

  • If the ~/.ssh/config file doesn't already exist, you will need to create it manually.

  • Windows users should be aware that Windows sometimes masks file extensions by default. This means that a file named config.txt might appear as config without the .txt extension. If you're on Windows, make sure the file is saved without any extension (i.e., just config).

In the file $HOME/.ssh/config, add the following configuration:

Host host-nickname
    HostName hostname
    User your-user-name-on-host
    IdentityFile ~/.ssh/id_ed25519
  • Replace host-nickname with a name you choose for your host (e.g., my-remote-server).
  • Replace hostname with the actual hostname or IP address of the remote server.
  • Replace your-user-name-on-host with the username you created on the host.

Once this configuration is added, you can SSH into the host using the alias you defined. For example:

ssh host-nickname

6. Setup VS Code

Installation

⚠️ Skip this section if you already have VS Code installed.

Go to the Visual Studio Code download page.

Windows:

  1. Download the Installer:

    • Select the appropriate installer (.exe) for your system architecture (x64 or x86).

  2. Run the Installer:

    • Once downloaded, run the installer.
    • Follow the on-screen prompts, and choose options such as adding VS Code to your system's PATH for easier command-line access.
    • Optionally, create a desktop shortcut.

  3. Complete Installation:

    • After installation, launch Visual Studio Code from the Start menu or desktop.

MacOS:

  1. Download the Installer:

    • Download the .zip file for macOS.

  2. Install VS Code:

    • Extract the .zip file.
    • Drag the Visual Studio Code app into the Applications folder.

  3. Launch VS Code:

    • Open VS Code from the Applications folder or search for it using Spotlight.

Adding Extensions

Remote Development

Install the Remote Development Extension Pack. This extension will detect WSL and SSH configurations and facilitate connexions to those remote environments by making them available from VS Code graphical interface in a dedicated side tab.

Additional Suggested Extensions

Here are a few other useful extensions to consider:

  • Python – For Python development support.
  • Jupyter – To work with Jupyter Notebooks.
  • Git Graph – Visualize your Git repositories and their history.
  • Protein Viewer – For viewing protein structures.

7. Conclusion

⚠️ From now on, most of your development tasks can be performed either from VS Code graphical interface or in VS Code integrated terminal.

In this tutorial, you've established a secure and efficient remote development environment. By leveraging SSH keys, you've enhanced security and eliminated the need for password-based authentication, allowing for seamless and safe access to your remote servers. Additionally, configuring SSH settings and utilizing the ~/.ssh/config file has streamlined your connection process, making it even more convenient to work remotely.

With Visual Studio Code's Remote Development Extension, you've unlocked a powerful workflow for editing code on remote machines directly within the VS Code interface. This extension allows for a smooth, integrated experience, bridging the gap between your local environment and remote systems without sacrificing usability or performance.

The next logical step in this setup is to configure your coding environment within the remote workspace. Setting up tools like Git for version control and Conda for managing dependencies and environments will ensure that you have a robust and reproducible development environment ready for any project.