How to set up a Linux development environment in Windows 10

In the past couple of years Microsoft has made some very intelligent decisions around their support and use of open source software and in particular coming up with a solution to modern web development on the Windows 10 platform. The solution they came up with was to provide a full Linux environment and kernel with (almost) seamless integration with development tools alongside the Windows 10 operating system.

This means that it is now possible to have the benefits of both Windows 10 and Linux without dual booting. Instead you boot into Windows 10, open a terminal and you have a full Ubuntu (or distro of your choice) environment to do your development work in. The integration between the two environments means that you can even run an X11 server and have GUI Linux apps running in Windows.

This is great news for developers at councils and other public sector bodies in the UK, as they usually have Windows machines and are not allowed to run Linux natively. In the past we've had to use Virtualbox which has led to performance issues and less than optimal development workflows.

This guide will help you get set up with WSL2 (Windows Subsystem for Linux) and prepare you for development work using Visual Studio Code as the IDE and Docker with Lando as the container based development environment, running on Ubuntu 20.04.

Set up WSL2

Microsoft have documented this step well so its best to follow their guide which they will keep updated: https://docs.microsoft.com/en-us/windows/wsl/install-win10

Install VS Code

Visual Studio Code (VS Code or VSCode) is Microsoft's open source IDE (Integrated Development Environment). It has a lot going for it and this guide will be using it so to follow along you'll need to install it. Download the Windows User Installer 64 bit (or 32 bit if you have an incompatible machine) version from https://code.visualstudio.com/Download

VSCode has a plethora of plugins available for it, depending on the kind of development you'll be doing you might want to install specific plugins.

Microsoft also provide a pretty good Terminal application which you can install from the Microsoft Store: https://www.microsoft.com/en-us/p/windows-terminal

You can also get it directly from GitHub: https://github.com/microsoft/terminal

If you install the GitHub version you'll need to keep it updated yourself. You can also find the preview version on the Microsoft Store which at the time of writing I have installed mostly as it provides clickable links which open links in your default browser.

You'll probably want the default to open your WSL2 Ubuntu environment rather than the current default PowerShell. To do this you'll need to open the settings file (which should open in VSCode if you've installed it). You should see an array under "profiles" which will container an object with your installed Ubuntu environment, it will look something like this:

{
    "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
    "hidden": false,
    "name": "Ubuntu-20.04",
    "source": "Windows.Terminal.Wsl"
},

Copy the value for the "guid" key and scroll to the top of the settings file where you'll see a key named "defaultProfile" with a different guid value. Overwrite that value with the one you just copied to your clipboard (the Ubuntu-20.04 one) and save settings file.

The next time you open the Windows Terminal the default should be your Ubuntu environment.

There is another useful thing to change which is to open your environment in your user's home directory in Ubuntu. Open up the Windows Terminal settings again and add a new key and value to the Ubuntu block. The key is "startingDirectory" and the value "\\\\wsl$\\Ubuntu\\home\\[your_username]" but with [your_username] changed to whatever your user is called in Ubuntu.

My user is tanc so mine looks like this:

{
    "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
    "hidden": false,
    "name": "Ubuntu-20.04",
    "startingDirectory": "\\\\wsl$\\Ubuntu\\home\\tanc",
    "source": "Windows.Terminal.Wsl"
},

If you don't know your username you can enter this in the Ubuntu shell:

whoami

Save the file and close and re-open Windows Terminal and you should now have Ubuntu 20.04 as your default environment and it should open in your user's home directory.

Configure Ubuntu for development work

You should now have a Ubuntu 20.04 instance installed. You can open this be starting the 'Ubuntu' Windows application, which will in turn open a basic terminal with the Ubuntu environment loaded, but I recommend using the Windows Terminal instead as it is more fully featured (see step above).

Install ZSH (Optional)

The default Bash environment is fine but you might want something a bit nicer to work with. Having tried various shells I find that ZSH is BASH syntax compatible but can be more heavily customised.

Install ZSH by opening your WSL2 Ubuntu terminal and entering:

sudo apt install zsh

It may be already installed by default.

Set it as your user's default shell:

sudo usermod -s /usr/bin/zsh $(whoami)

Install Oh-My-ZSH (Optional)

Oh-My-ZSH provides some useful additions to the ZSH shell. There are alternatives but Oh-My-ZSH is one of the most widely used and is easy to find plugins and support for.

Install it with:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

I really like the Spaceship prompt which you can install with:

git clone https://github.com/denysdovhan/spaceship-prompt.git "$ZSH_CUSTOM/themes/spaceship-prompt" --depth=1

Symlink spaceship.zsh-theme to your oh-my-zsh custom themes directory:

ln -s "$ZSH_CUSTOM/themes/spaceship-prompt/spaceship.zsh-theme" "$ZSH_CUSTOM/themes/spaceship.zsh-theme" 

To activate it as your prompt you need to edit your .zshrc file using your editor of choice. It can be quite easily edited with vscode using the handy integration with the shell:

code ~/.zshrc

This will open your ~/.zshrc file in VS Code.

Around line 11 you will see ZSH_THEME="robbyrussell" or similar. Change that so it reads ZSH_THEME="spaceship" and save the file but keep it open for some further edits.

You can now close and reopen your terminal and you should see a different default prompt.

Install Oh-My-ZSH plugins (Optional)

Plugins enhance the ZSH shell experience. These are my recommendations:

Install the two that don't come with oh-my-zsh:

git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/supercrabtree/k $ZSH_CUSTOM/plugins/k

Then edit your .zshrc file in your editor:

code ~/.zshrc

Move to the section about plugins. By default it will have just the git plugin enabled and should look something like:

plugins=(git)

Change it to enable the others:

plugins=(
  git
  zsh-autosuggestions
  k
  history-substring-search
)

At the bottom of the file I like to add some aliases:

alias l="k -h"
alias ll="k -h"
alias explorer="explorer.exe ."

Save that file and reopen your shell and you should have the plugins enabled. Now as you type suggestions from you history will be displayed inline. You can also use the arrow keys to scroll through your history with a partial match.

Aliasing l and ll to k shows a nicer directly listing. Try it:

l

Install Docker

Docker is a very important part of the development environment as it allows you to run the server software required in 'containers' which keep them isolated from your main development environment. This means that instead of trying to maintain and/or run different versions of Apache, MySQL or other servers you can quite easily spin up and down containers which have the specific version of software you need. These can be orchestrated to work together in a network so you can have multiple containers working together to mimic the eventual live set up you might have. To orchestrate the containers you can use docker-compose but we will use Lando which is a friendly layer on top of docker-compose.

First we need docker installed. Previously we advised installing Docker within the Linux environment but recent updates to Docker Desktop has meant the integration is now a lot better between the systems. This is now the preferred method and is easy to install, follow the provided guide.

Install Lando

Now we want to install Lando within the Ubuntu environment which will provide the means of easily orchestrating a set of containers to provide the servers we need to serve for example a Drupal web site.

Installing Lando on Linux is easy:

wget https://files.devwithlando.io/lando-stable.deb
sudo dpkg -i lando-stable.deb

Remove the downloaded deb package:

rm lando-stable.deb

Add your user to the docker group:

sudo usermod -aG docker $USER

You are now set up and ready to develop. You might want to test that containers and Lando work as they should. For a simple Lando test project follow the Hello World! example here: https://docs.lando.dev/basics/first-app.html

Troubleshooting

Docker or Lando not working

You may need to delete a docker created json file:

rm ~/.docker/config.json
Back to blog