syxo / windows-wsl-ubuntu-setup

Instructions to make Windows 10 with the Windows Subsystem for Linux (WSL) setup fast and efficient for developing software in Go, C# (.NET Core), Java, Python, and NodeJS, and web front-ends in React. This guide uses Ubuntu 18.04 as the OS running within WSL.

Windows 10 and Ubuntu on Windows Subsystem for Linux (WSL) Setup Guide for Web App Developers

Instructions to make Windows 10 with the Windows Subsystem for Linux (WSL) setup fast and efficient for developing web apps in Go, C# (.NET Core), Java, Python, and NodeJS, and web front-ends in React. This guide uses Ubuntu 18.04 as the OS running within WSL.

Turn on Windows Subsystem for Linux

WSL is not enabled in Windows 10 by default. To enable it:

1. Close all open applications as a reboot will be required later
2. Open the Windows start menu
3. Start typing "turn windows features". Observe the first and only item in the search results is Turn Windows features on and off.
4. Select Turn Windows features on and off from the search results. An elevated prompt appears.
5. Verify the publisher is displayed as Microsoft Windows in the elevated prompt.
6. Enter your administrator account credentials into the elevated prompt and proceed. A Windows Features dialog box appears.
7. Scroll to the bottom of the list of features and check the box next to Windows Subsystem for Linux.
8. Press Ok. An installer dialog with a progress bar appears. When it's done, you will be prompted to reboot. Select Restart now.

Install Windows Subsystem for Linux

The Windows 10 App Store is the most straightforward way to install Ubuntu in WSL. Some organizations disallow use of the app store on their Windows machines, in which case you must install Ubuntu manually:

1. After restarting your PC from the previous set of steps, visit https://docs.microsoft.com/en-us/windows/wsl/install-manual and select the Ubuntu 18.04 distro. Alternatively, you can download the Ubuntu 18.04 distro at https://aka.ms/wsl-ubuntu-1804.
2. After the download is complete, run the .appx file that was downloaded. An installer window will appear. NOTE: Whatever directory you run the installer from is where WSL will be installed to. You cannot change this directory post-installation.

If the .appx file appears un-runnable in Windows, see the "Manual Appx unpackaging and installation" portion of this guide. Otherwise, continue with step 3 below.

3. Launch the installer. A Windows Command Prompt titled Ubuntu will appear with the text Installing, this may take a few minutes...
4. After a short while, a prompt will appear asking for a UNIX username. Enter a name you will remember and press Enter.
5. A prompt will appear asking for a UNIX password. Enter a strong password and press Enter.
6. A prompt will appear asking for you to retype your password. Re-enter the same password you just typed in the previous step and press Enter. A Bash prompt appears with your username and machine name, e.g. username@machinename:~$
7. Right-click on the Ubuntu app icon in your Windows taskbar and select Pin to taskbar.

Workaround: Manual Appx unpackaging and installation

This section is only meant to work around a problem where Windows 10 doesn't recognize .appx files as executable, thus preventing readers from completing the steps outlined in the previous section.

1. Change the extension on the Ubuntu file you downloaded from .appx to .zip.
2. Open the zip file in Windows
3. Elect to extract the contents of the zip file to somewhere on your computer.
4. Open the extracted files on your computer
5. Find the installer exe file and run it. NOTE: Whatever directory you run the installer from is where WSL will be installed to. You cannot change this directory post-installation.
6. Resume step 4 from the previous section

Update the OS and install common tools

The first thing you should do is get the latest security updates:

sudo apt update && sudo apt dist-upgrade -y

Next, install some common tools you'll need later:

sudo apt install \
openjdk-8-jdk-headless \
maven \
build-essential \
apt-transport-https \
ca-certificates \
curl \
software-properties-common \
apache2-utils \
make

Change Colors

Users interact with WSL through the Windows 10 Command Prompt. To change the colors for the Command Prompt, left-click on the Ubuntu icon on the top-left corner of the WSL window and select Properties > Colors.

Access the C drive from Ubuntu

Accessing Windows files from Ubuntu is possible by navigating to the C drive, which is listed in mnt:

cd /mnt/c

Java and Maven

sudo apt install openjdk-8-jdk-headless maven

Run javac -version and look for javac 1.8.0_222 (or newer) to verify success

Go

sudo apt install golang-go

Run go version and look for go version go1.10.4 linux/amd64 (or newer) to verify success

Python

sudo apt install python3-minimal

Run python3 --version and look for Python 3.6.8 (or newer) to verify success

NodeJS

sudo apt install build-essential
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt install nodejs

Run npm --version and look for 6.11.2 (or newer) to verify success

Periodically, you will want to update NPM to the latest available version. Do so by running:

sudo npm install -g npm

.NET Core

sudo apt install apt-transport-https ca-certificates
wget -q https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt update && sudo apt install dotnet-sdk-3.1 -y
rm -f packages-microsoft-prod.deb

Run dotnet --version and look for 3.1.100 (or newer) to verify success

Optional: Disable .NET Core telemetry

1. Run nano ~/.profile
2. Type export DOTNET_CLI_TELEMETRY_OPTOUT=true at the bottom of the file
3. Save and exit
4. Restart the WSL command prompt

You can also set DOTNET_SKIP_FIRST_TIME_EXPERIENCE to true when editing .profile to fix the following warning that may appear during .NET Core compiles: "Permission denied to modify the '/usr/share/dotnet/sdk/NuGetFallbackFolder' folder."

Docker and Docker Compose

WSL is incapable of running the Docker daemon. To use Docker commands in a WSL terminal, you must send them to Docker for Windows for execution. Setting up this bridge is not straightforward and poorly documented, but it can be done with just a few steps.

1. Install Docker for Windows
2. Return to the Ubuntu command prompt
3. Run the following commands:

sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88

Running "sudo apt-key fingerprint 0EBFCD88" should display:

pub   rsa4096 2017-02-22 [SCEA]
      9DC8 5822 9FC7 DD38 854A  E2D8 8D81 803C 0EBF CD88
uid           [ unknown] Docker Release (CE deb) <[email protected]>
sub   rsa4096 2017-02-22 [S]

Next, run:

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install docker-ce
docker --version

Running "docker --version" should display "Docker version 19.03.1, build 74b1e89" or similar.

Install Docker Compose:

sudo curl -L "https://github.com/docker/compose/releases/download/1.25.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Running "docker-compose --version" should display "docker-compose version 1.25.0, build 0a186604".

Ensure you can run Docker commands without sudo:

sudo usermod -aG docker $USER

Following the above commands will install Docker in WSL, but again, the daemon will not start. Follow the instructions below to create a bridge between Docker in WSL and Docker for Windows:

1. Open the Docker for Windows app in Windows 10 and navigate to the General tab.
2. Check the box that says Expose daemon on tcp://localhost:2375 without TLS. Docker for Windows will restart momentarily.
3. Return to the Ubuntu command prompt.
4. Run nano ~/.profile, add export DOCKER_HOST=tcp://0.0.0.0:2375 to the end of the file, and save
5. Restart Ubuntu WSL
6. Once Ubuntu WSL is restarted, type docker run hello-world and press Enter. You should see a lengthy output that says somewhere in the middle, "Hello from Docker!"

AWS CLI tools

sudo apt install awscli

Run aws --version to verify success.

AWS CLI tools can alternatively be installed and updated using pip instead of the central repositories. See Install AWS CLI on Linux for instructions. The benefit of using pip is a more up-to-date version of the tools.

Git configuration

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

See Customizing Git Configuration for more details. You can edit the global Git config file by running nano ~/.gitconfig in a terminal window.

SSH Keys for GitHub/GitLab

1. Run ssh-keygen -o -t rsa -b 4096 -C "your comment goes here"
2. Enter a passphrase
3. Run cat ~/.ssh/id_rsa.pub
4. Copy the output from cat and paste it into GitLab and GitHub's SSH key sections for your profile
5. Run ssh -T [email protected] to verify the key is recognized and working with GitLab
6. Run ssh -T [email protected] to verify the key is recognized and working with GitHub.com

GPG Keys for signing commits

Taken from https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/index.html.

1. Run gpg --full-gen-key
2. Choose "RSA"
3. Choose 4096 bits
4. Choose 2y (or a timeframe of your choosing)
5. Provide the other required inputs
6. Run gpg --list-secret-keys --keyid-format LONG [email protected] (replace [email protected] with the email you used previously)
7. Copy the GPG key ID that starts with sec. E.g. in sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC], the key ID is 30F2B65B9246B6CA
8. Run gpg --armor --export 30F2B65B9246B6CA
9. Run git config --global user.signingkey 30F2B65B9246B6CA

To sign commits, the only difference is the addition of the -S flag:

git commit -S -m "My commit msg"