Installing GitKraken in WSL 2
Update April 2021
WSLg, Microsoft’s native Linux GUI solution, is now available on the Windows Insider dev channel. If you install and configure WSLg, you can skip pretty much this entire article and simply run
wget https://release.gitkraken.com/linux/gitkraken-amd64.deb
sudo dpkg -i ./gitkraken-amd64.deb
sudo apt-get install -f
gitkrakenOur login flows for linking your hosting provider accounts will even work through your default browser in Windows :)
Motivation
The Windows Subsystem for Linux provides a Linux environment integrated tightly into Windows 10. WSL 2 accomplishes this by running a Linux kernel in a virtual machine. Microsoft recommends that WSL 2 users store their documents and files within the Linux root filesystem to take advantage of the file performance benefits that WSL 2 aims to provide.
Windows apps can access this filesystem from \\wsl$\Ubuntu(for example), where it appears to act like a network share. Mounting this directory in Windows applications generally works fine, but at the time of this writing, accessing it has relatively poor performance, which can slow down filesystem heavy operations like checkout enough to make using the Windows version of GitKraken to interact with repos on that filesystem undesirable.
This document is a guide for tinkerers and advanced users who wish to install the Linux version of GitKraken within the WSL 2 virtual machine to get better performance interacting with files in the Linux root filesystem. This technique is unsupported. Follow this guide at your own risk — I’m publishing it as an adventurous tinkerer, not a representative of Axosoft. That being said, feel free to ping me in the official GitKraken slack if you have any feedback.
tl;dr
In Windows: Install an X server, allow it to accept incoming connections from public networks, and, optionally, tighten the firewall rules to only allow incoming connections from the WSL VM.
In Linux: set theDISPLAY environment variable, download and install the Linux version of GitKraken, and run it.
Before we begin
- Make sure you have WSL 2 installed and configured. I’m using Ubuntu 18.04 for this tutorial
- You’ll need an internet connection and permission to edit your computer’s firewall rules
We’re first going to install and configure an X server for windows, then we’re going to install GitKraken in the Linux userspace.
Install an X server
Unix compatible systems (historically*) use a protocol called the X windowing system to display GUIs. Computers with screens run X servers, then applications implement X clients and connect to X servers to render graphics. It works locally and over a network (and even over SSH), so that you can still use graphical applications on a server or time-shared system that doesn’t have a display. This isn’t a common use case on your average Linux PC, but we can take advantage of this feature to run GitKraken in our headless Linux environment and control it from Windows.
We need to install an X server on Windows for GitKraken to connect to. I personally have been using X410, but for the purpose of this guide we’re going to install VcXsrv because it’s free and works just as well in my testing.
*Avid Linux users may be aware that alternatives to X such as Wayland are becoming more popular, but X is showing no signs of going away.
Download VcXsrv
Download VcXsrv from SourceForge. Go ahead and install it, all the defaults should be fine.
Generate a config file
On the last page of the installer, there’s a button to launch the configuration tool. Open it, or, if you already closed the installer, find ‘XLaunch’ under ‘VcXsrv’ in your start menu and open it.
- Display settings: select “Multiple windows” and set the display number to -1. (default)
- Client startup: select “Start no client” (default)
- Extra settings: leave everything as is but check “Disable access control”. By default, VcXsrv only allows incoming connections from localhost and the like, but WSL 2 VMs have their own IP addresses. We need VcXsrv to accept connections from them. Don’t worry, we’ll go over firewall configuration to make this safer later.
- Save the configuration file somewhere convenient. You’ll double click it whenever you want to start the X server in the future. I put it on my desktop.
Before you click finish to start the server, a note about networking. As previously mentioned, WSL 2 VMs have their own IP addresses (though apparently this may change — if it does, the firewall step will go away completely and this guide will be updated). Windows provides a dedicated virtual network interface for interacting with these VMs. This network is flagged as “public”.
When you start the VcXsrv for the first time, windows firewall will prompt you about allowing incoming connections to it. Check public networks.
Doing so will give all incoming connections from public networks access to your X server. Our next step will be configuring a tighter firewall rule to only allow incoming connections from the WSL VMs.
You may now click finish in the configurator.
Configuring Windows Firewall
As previously mentioned, your X server is now open and accessible to incoming connections from any public networks you connect to your computer. Let’s write a firewall rule that’s more restrictive instead.
If you’re following along on a desktop at home, or are otherwise certain that you will only ever connect to networks you trust, (or just don’t care), feel free to skip this— the X server is in a working state and ready to go. You can always come back and configure the firewall later.
We’re going to do two things: create our new, restrictive firewall rule, and disable the automatic ones that Windows generated automatically when it prompted you to allow incoming connections.
First, use ifconfig in your Linux shell to make note of the WSL VM’s IP address. Look for the inet field on the first line under eth0
Next, get to the “Windows Defender Firewall with Advanced Security” page. You should be able to type that entire long name into the Start menu to find it. It looks like this
We need to create a new inbound rule. Select “inbound rules” in the left panel, then click “new rule” in the actions panel.
The rule creation wizard that appears has a lot of screens, so for the sake of scroll wheels everywhere I’m publishing screenshots of the rule creation as a Google Slides slideshow. If you already know what you’re doing, we need an inbound rule, that applies only to our X server, that allows connections from the range of remote IPs the WSL VM may take. I’m not a windows firewall expert, so if you spot a mistake please reach out.
Finally, we need to disable the automatic rules that Windows generated after we clicked through the firewall prompt when we first launched VcXsrv. There should be two inbound rules named “VcXsrv windows xserver”. Right click to disable them both.
Install GitKraken
Download and install the .deb
Run the following commands from your shell
wget https://release.gitkraken.com/linux/gitkraken-amd64.deb
sudo dpkg -i ./gitkraken-amd64.deb
sudo apt-get install -fIf you plan on using our hosting provider integrations (recommended), you’ll need a web browser so you can log in to those services. This guide used to recommend installing chromium. Recent versions of Ubuntu try to get you to install chromium over snap, but snap didn’t work for me in WSL, so let’s install firefox.
sudo apt install firefoxBy default, the Ubuntu install from the Microsoft store doesn’t come with an emoji font. We like to use emoji in our release notes, so if you want those, go ahead and install an emoji font 😉
sudo apt install fonts-noto-color-emojiAnd if you find the “open file” dialog has a bunch of squares instead of letters, go ahead and install the default Ubuntu font
sudo apt install fonts-notoSet the DISPLAY environment variable in your bash_profile
You may need to do this every time you start a new WSL session. You can add it to your .bash_profile to do so.
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0Also, if you run into issues working with SSH remotes (AUTH SOCK not available), you might need to add some code to start your SSH agent on login. See this github issue: https://github.com/Microsoft/WSL/issues/3183#issuecomment-604437585
Display Scaling
If you have a high resolution display like I do, you may need to also set the GDK_SCALE environment variable.
export GDK_SCALE=2Start GitKraken
Gitkraken is installed in your path and can be invoked from the shell. Use & after any given command to put it in the background.
gitkraken &You should see our splash screen appear! The icon in your taskbar will be that of the X server, not GitKraken’s. It may take a moment to connect, but it should only take a moment. Unfortunately, if the X server is unreachable, things seem to hang instead of failing with an error message. If Gitkraken doesn’t open or log any output, try running something like xeyes (sudo apt install x11-apps).
My tip: GitKraken, as well as several other Linux GUIs I tried, sends occasional messages to stdout, which still appear in your prompt even when the process is backgrounded. I like to start it in a tmux session so I don’t have to look at the output. Start tmux by typing tmux, start gitkraken with gitkraken, and then press ctrl+b then d to detach from the session. You can re-attach with tmux a.
