New WSL2 image

Some packages whould be installed in the host machine before starting, such as:

• Visual Studio Code
• Git for Windows

1. (Skip this step if you've done it before) Configure git on your Windows host machine

If you havent't already installed Git for Windows, install it via Powershell:

winget install --id Git.Git -e --source winget

You can check the box in the installation to have the git-credential-manager build in the Git for Windows installation. If you haven't done that, install it via Powershell doing:

dotnet tool install -g git-credential-manager

After that, the following steps are to be executed in your git bash.

Configure git-credential-manager, than login to your github with it. If you are having trouble login via Web Browser, via devide code should work as well:

git-credential-manager configure
git-credential-manager github login --no-ui

Configure your user.name and user.email on your local git. These should be the same you will use in the next step for the signin configuration!

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Now configure your GPG Key for commit signing. This key will be used on WSL2 as well. All default prompts are enough, but your name and email should be the same as your git config. Dont forget your passphrase!

gpg --full-generate-key

Now, you need to copy your sec key for the next command. Do this by running the gpg --list-secret-keys --keyid-format=long command:

$ gpg --list-secret-keys --keyid-format=long
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
/c/Users/adowell/.gnupg/pubring.kbx
-----------------------------------
sec   rsa3072/AA33332221111111 2023-12-20 [SC]
      EDDDAA33332221111111AA33332221111111DDDE
uid                 [ultimate] Andre Mac Dowell <[email protected]>
ssb   rsa3072/5BA547748D7EB97A 2023-12-20 [E]

In this example, the key is AA33332221111111. Run the command below, copy the key block and add it as a new GPG key on your Github Settings page:

gpg --armor --export AA33332221111111

Again, in case you forgot, you need to copy the key block from the previous command and add it as a new GPG key on your Github Settings page!!

Now, get the public key to add it to your git config. In this example, the key is EDDDAA33332221111111AA33332221111111DDDE

$ gpg --list-keys

/c/Users/adowell/.gnupg/pubring.kbx
-----------------------------------
pub   rsa3072 2023-12-20 [SC]
      EDDDAA33332221111111AA33332221111111DDDE
uid           [ultimate] Andre Mac Dowell <[email protected]>
sub   rsa3072 2023-12-20 [E]

Now add the key and change the default config to always sign commits on the Windows Host. You will use the same public key for your git configuration on WSL2 on the next step:

git config --global user.signingkey EDDDAA33332221111111AA33332221111111DDDE
git config --global commit.gpgsign true

2. (Every step from there forward is on your Ubuntu WSL image!) Update your base packages

sudo add-apt-repository ppa:git-core/ppa
sudo apt-get update && sudo apt-get upgrade

3. Python3 setup

Should already be installed, so just install pip sudo apt-get install python3-pip

You should probably also install venv: sudo apt-get install python3-venv

4. Symbolic link to repo folder on Windows Host

Change target to where your repos are on the Windows Host ln -s -t . /mnt/c/Users/$USER/repos/

5. Install VS Code

Do this in your repo folder and VS Code will install automatically if it's not installed. code .

6. Install Docker and Docker Compose

This should suffice, you can safely copy+paste the entire thing

sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt-get update && sudo apt-get upgrade
sudo apt-get install ca-certificates curl gnupg lsb-release
sudo apt-get autoremove
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Now you can test if it worked

docker --version
docker compose version

7. Create useful aliases

Open new alias file vim ~/.bash_aliases

Add this at the end and save

alias docker-compose="docker compose"
alias python=python3
alias pip=pip3
alias venv-create-and-activate='python -m venv venv && source venv/bin/activate'
alias venv-activate='source venv/bin/activate'

After saving the file, source your .bashrc file source ~/.bashrc

8. Add additional permissions for Docker

Restart your cli after this step. Don't worry if it says that the group already exists.

sudo groupadd docker
sudo usermod -aG docker $USER

If you are getting an error of this type on the /var/log/docker.log:

Error initializing network controller: error obtaining controller instance: failed to register "bridge" driver: unable to add return rule in DOCKER-ISOLATION-STAGE-1 chain

Try these two steps: 1) Run sudo update-alternatives --set iptables /usr/sbin/iptables-legacy; then 2) Add net.ipv4.ip_forward = 1 to your /etc/sysctl.conf file.

9. SQL Tools installation

This step only works up until Ubuntu-22.04 as of October-2025. If you REALLY want to use Ubuntu 24.04, you have to change the $(lsb_release -rs) parameter to 22.04 hardcoded.

Just run this entire thing

curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo apt-get install mssql-tools18
echo 'export PATH="$PATH:/opt/mssql-tools18/bin"' >> ~/.bashrc
source ~/.bashrc

10. Finish your git configuration on WSL2

Get your GPG pub key on the Windows Host machine again (Git Bash):

gpg --list-keys

Now add the key and change the default config to always sign commits on WSL2

git config --global user.signingkey EDDDAA33332221111111AA33332221111111DDDE
git config --global commit.gpgsign true

Also configure you user.name and email with the same properties you did on the Windows host machine:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Make a symbolic link for the .gnupg folder

ln -s -t . /mnt/c/Users/$USER/.gnupg/

A bit of magic so that git understands that we know what we are doing

echo 'export GPG_TTY=$(tty)' >> ~/.bashrc && source ~/.bashrc

If your git is installed locally, the begining of the path will be PREFIX="/mnt/c/Users/$USER/AppData/Local/Programs". If it's installed for all users, it will likely be PREFIX="/mnt/c/Program\\ Files"

Direct credencial helper to host machine configurations, then test if it worked.

git config --global credential.helper "$PREFIX/Git/mingw64/bin/git-credential-manager.exe"

Direct your gpg usage to the installed on the Windows Host machine. If the Git installation is for all users, For some reason, the prefix for the gpg.program doesnt need the double \\.

git config --global gpg.program "$PREFIX/Git/usr/bin/gpg.exe"

If you are having errors related to keyboxd on WSL but not on the Windows Host, you might need to comment the use-keyboxd line on the ~/.gnupg/common.conf file (which should be the same on both WSL and Windows Host because of the symbolic link to the Windows Host).

11. Install the dotnet SDK

Pretty straightforward, feel free to change versions accordingly

sudo apt-get install -y dotnet-sdk-9.0