How to configure working setup on WSL

Setup for WSL

Hello! This is a complete guidance on how to setup your environment using vscode, wsl2, ssh & gpg keys and others.

Prerequisites

• Windows 10 (version 1903 or higher) or Windows 11

Presetup

If not installed already, you may find useful if you have these tools:

• Windows Terminal
• PowerShell 7

Install Windows Terminal

• Go to Windows Terminal installation
• Click on Install Windows Terminal, this will redirect you to Microsoft Store
• Search for Windows Terminal
• Click on Download

Install PowerShell 7

• Go to the PowerShell GitHub Releases page: https://github.com/PowerShell/PowerShell/releases
• Download the latest .msi installer for your system architecture (e.g., x64).
• Run the installer and follow the setup wizard:
• Choose Add to PATH (recommended)

After installation, open Windows Terminal and click the dropdown arrow to select PowerShell 7

Verify Installation

Open Windows Terminal

• Run:

  $PSVersionTable.PSVersion
  

  You should see version 7.x.x

Installing WSL 2 via Windows Terminal / PowerShell

• Press Win key, type Windows Terminal
• Right-click on PowerShell tab and select Run as administrator
• Run the following command

  wsl --install
  

  This command will enable the required Windows features, download and install the latest WSL kernel, set WSL 2 as the default version, install Ubuntu (default distro)

• Restart Your Computer
• Verify Installation After reboot, open Windows Terminal and run

  wsl --list --verbose
  

  You should see your installed Linux distro with version 2.

Optional: Install a Different Linux Distro

To view available distros:

wsl --list --online

To install a specific distro (e.g., Debian):

wsl --install -d Debian

Install VSCode

Follow these steps to install VS Code, a lightweight and powerful source code editor for Windows, macOS, and Linux.

• Go to the official download page: https://code.visualstudio.com/Download

Click on Windows > User Installer (or System Installer if you prefer system-wide installation).

• Launch the downloaded .exe file.

Follow the setup wizard:

Accept the license agreement, choose the installation location, check the following options:

• Add to PATH
• Register Code as an editor for supported file types
• Add Open with Code to context menu

Click Install and wait for the process to complete.

• Launch VS Code

After installation, VS Code will launch automatically. You can also open it anytime by searching for “Visual Studio Code” in the Start menu.

Configure GIT on WSL

• Open Windows Terminal, then select your Linux distro (e.g., Ubuntu) from the dropdown.

• Run the following command to install Git:

  sudo apt update && sudo apt install git -y
  

Verify the installation:

git --version

Configure Git

Set your global Git username and email:

git config --global user.name "Your Name"
git config --global user.email "you@your_email.com"

Optional: Set your preferred editor (e.g. VS Code):

git config --global core.editor "code --wait"

Set Up SSH Keys

Generate a new SSH key:

ssh-keygen -t ed25519 -C "you@your_email.com"

Press Enter to accept the default file location and optionally set a passphrase.

Import public key

Copy your public key to your clipboard:

cat ~/.ssh/id_ed25519.pub

You can paste the content into SSH keys from either Github or other platform you are using: e.g. Gitlab, Bitbucket etc.

(Optional) Install SSH agent

This will help you automate ssh passphrase.

• Step 1: Install Keychain

Update your package list and install keychain:

sudo apt update && sudo apt install keychain -y

• Step 2: Configure Your Shell to Use Keychain and SSH Agent

Edit your shell configuration file (e.g., ~/.bashrc) and add the following lines at the end:

env=~/.ssh/agent.env

agent_load_env () { test -f "$env" && . "$env" >| /dev/null ; }

agent_start () {
    (umask 077; ssh-agent >| "$env")
    . "$env" >| /dev/null ; }

agent_load_env

# agent_run_state: 0=agent running w/ key; 1=agent w/o key; 2=agent not running
agent_run_state=$(ssh-add -l >| /dev/null 2>&1; echo $?)

if [ ! "$SSH_AUTH_SOCK" ] || [ $agent_run_state = 2 ]; then
    agent_start
    ssh-add
elif [ "$SSH_AUTH_SOCK" ] && [ $agent_run_state = 1 ]; then
    ssh-add
fi

unset env

More info on auto-launching SSH agent (GitHub Docs)

• Step 3: Reload Your Shell Configuration

Apply the changes by running:

source ~/.bashrc

Or restart your terminal session.

• Step 4: Add Your SSH Key to Keychain

The first time you start a new terminal session, you’ll be prompted for your SSH key passphrase. Keychain will cache it for future sessions:

keychain id_ed25519

• Step 5: Verify SSH Agent is Running

Check that your key is loaded:

ssh-add -l

You should see your key listed.

Installing Gpg4win with Kleopatra via Winget

What is Gpg4win?

Gpg4win is a Windows suite for secure file and email encryption using OpenPGP and S/MIME. It includes:

1. GnuPG – the core encryption engine
2. Kleopatra – graphical certificate manager
3. GpgOL – Outlook plugin
4. GpgEX – Windows Explorer integration

• Step 1: Open Windows Terminal or PowerShell

Press Win + X and choose Windows Terminal or PowerShell.

Install Gpg4win using winget

Run the following command:

winget install -e GnuPG.Gpg4win

-e ensures an exact match to avoid ambiguity.

Winget will download and install the latest version of Gpg4win, including Kleopatra.

Launch Kleopatra

After installation:

Press Win and search for Kleopatra. Click to launch the application.

Create a Key Pair

To create a new key pair in Kleopatra:

1. go to File → New OpenPGP key pair
2. Enter your name and email.
3. Set a strong passphrase.
4. Complete the wizard to generate your key.

Verify Installation

You can verify that Gpg4win is installed and working:

• Open Kleopatra and check for your key.
• Reload you PowerShell terminal.
• Run this in PowerShell to check GPG version:

gpg --version

Configure GPG key to Git & WSL

Export the Key for WSL2

• In Kleopatra, right-click your certificate from the list displayed and choose Export.
• Save the file as something like gpg-public.asc in a known location (e.g. Documents).
• Export the private key by right-clicking and choosing “Backup Secret Keys”, saving it as gpg-private.asc.

Please note: If you set a passphrase, when exporting the private key, you will be prompted to provide that passphrase. Also, if you see you gpg private key at 0 KB, you may need to wait few minutes until decryption is completed or to re-export it once again.

Import the Key into WSL2

Open your WSL2 terminal.

Navigate to the folder where the key is saved (e.g., /mnt/c/Users/YourUsername/Documents/):

cd /mnt/c/Users/YourUsername/Documents/

Import the private key:

gpg --import gpg-private.asc

Import the public key:

gpg --import gpg-public.asc

Verify if the key can be displayed from WSL:

gpg --list-secret-keys --keyid-format LONG

Note: you may see this warning message gpg: conversion from 'utf-8' to 'CP437' failed: Illegal byte sequence, it can be ignored.

Your output should look something like:

sec   ed25519/ABCDEF1234567890 2025-05-24 [SC]
      ABCDEF1234567890ABCDEF1234567890ABCDEF12
uid           [ultimate] YOUR NAME <your.email@your_email.com>

Note: the key ID is after ed25519/ (e.g., ABCDEF1234567890).

Troubleshooting: Unknown Trust Level in GPG

If you see [unknown] at the trust level, like this:

uid           [unknown] YOUR NAME <your.email@your_email.com>

Follow these steps to fix it:

1. Edit the GPG key in WSL

You can use either your email or the key ID:

# Using your email
gpg --edit-key your.email@your_email.com

# Or using the key ID
gpg --edit-key ABCDEF1234567890

2. Set the trust level

At the gpg> prompt, type:

gpg> trust

GPG will ask how much you trust this key. Since you generated it, choose the highest trust level:

Please decide how far you trust this user to correctly verify other users' keys
  1 = I don't know or won't say
  2 = I do NOT trust
  3 = I trust marginally
  4 = I trust fully
  5 = I trust ultimately
  m = back to the main menu

Your decision? 5

Type 5 (ultimate trust), then confirm with y and quit with q.

In Kleopatra, you can also set trust by double-clicking your certificate and adjusting trust settings in the UI.

Configure Git with the new GPG key

Copy the key ID from your gpg key and configure git yo use this key:

# Replace "ABCDEF1234567890" with your key ID
git config --global user.signingkey ABCDEF1234567890
git config --global commit.gpgsign true

Configure WSL

Create a file called .gpg-setup.sh in the home folder of your wsl user and add those lines:

# Set GPG_TTY for the current terminal
export GPG_TTY=$(tty)
 
# Launch the GPG agent if not already running
gpgconf --launch gpg-agent

Add this code to your ~/.bashrc file:

# Set gpg TTY and launch gpg-agent
source ~/.gpg-setup.sh

Close or reload your terminal

source ~/.bashrc

Create a gpg configuration file ~/.gnupg/gpg-agent.conf.

Add this line into the file

pinentry-program "/mnt/c/Program Files (x86)/Gpg4win/bin/pinentry.exe"

Kill the gpg process that it running (it will restart automatically at the next gpg action needed)

gpgconf --kill gpg-agent

Add the Public Key to Github/Gitlab/Bitbucket

Export your public key from WSL2:

gpg --armor --export you@your_email.com

Copy the entire output (including -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK-----)

Go to your provider (Github, Gitlab, etc) and click “Add key” under GPG keys.

Paste the public key and save.