Skip to content

Commit

Permalink
[docs] Simplify WSL2 installation steps (#3246)
Browse files Browse the repository at this point in the history 
* Simplify WSL2 installation steps
- The wsl --install command was backported to Windows 2004 and higher. This drastically simplifies installation of WSL2. https://devblogs.microsoft.com/commandline/install-wsl-with-a-single-command-now-available-in-windows-10-version-2004-and-higher/
- Windows 10 1903 and 1909 are out of support at the moment of writing (https://docs.microsoft.com/en-us/windows/release-health/release-information), and also don't support the wsl --install command. Therefore we don't mention them anymore in the installation guide.
  • Loading branch information
@dennisameling
dennisameling committed Sep 17, 2021
1 parent 59d496b commit 1574b48
Showing 1 changed file with 19 additions and 22 deletions.
41 changes: 19 additions & 22 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,42 +49,39 @@ ddev poweroff && brew upgrade drud/ddev/ddev

### Installation or Upgrade - Windows (WSL2)

**This is the recommended installation method for all Windows users that are on Windows 10 [1903.1049, 1909.1049](https://devblogs.microsoft.com/commandline/wsl-2-support-is-coming-to-windows-10-versions-1903-and-1909/), 2004 or higher** If you don't have this version yet, or if you don't want to use WSL2, please follow the legacy instructions for Windows below.
**This is the recommended installation method for all Windows users that are on Windows 10 2004 or higher**. If you don't have this version yet, or if you don't want to use WSL2, please follow the legacy instructions for Windows below.

**All Windows 10 editions (including Windows 10 Home) support WSL2**. Docker Toolbox support for DDEV has been removed. If you're already familiar with DDEV on Windows, you might have been using NFS for better filesystem performance. **You won't need NFS anymore once you switch to WSL2**, since it provides awesome filesystem performance out of the box.

The WSL2 install process involves:

* Installing Chocolatey package manager (optional).
* One time initialization of mkcert.
* Installing WSL2, setting version 2 as the default version, and installing a distro like Ubuntu.
* Installing WSL2 and installing a distro like Ubuntu.
* Installing or upgrading to the latest Docker Desktop for Windows with WSL2 enabled.
* Installing DDEV inside your distro.

We'll walk through these in more detail. You may prefer other techniques of installation or may not need some steps, but this is the full recipe:

1. If you have previously installed Docker Toolbox, please completely [uninstall Docker Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/#how-to-uninstall-toolbox).
2. **Chocolatey:** We recommend using Chocolatey for [Chocolatey](https://chocolatey.org/install) installing required Windows apps like mkcert. In an administrative PowerShell, `Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))`
2. **Chocolatey:** We recommend using [Chocolatey](https://chocolatey.org/install) for installing required Windows apps like mkcert. In an administrative PowerShell, `Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))`
3. In an administrative PowerShell: `choco install -y mkcert`
4. In administrative PowerShell, run `mkcert -install` and answer the prompt allowing the installation of the Certificate Authority.
5. In administrative PowerShell, run the command `setx CAROOT "$(mkcert -CAROOT)"; If ($Env:WSLENV -notlike "*CAROOT/up:*") { setx WSLENV "CAROOT/up:$Env:WSLENV" }`. This will set WSL2 to use the Certificate Authority installed on the Windows side.
6. Install WSL2. In an administrative PowerShell `Enable-WindowsOptionalFeature -Online -FeatureName $("VirtualMachinePlatform", "Microsoft-Windows-Subsystem-Linux")` (Your computer will reboot.) (See [detailed documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10).)
7. Download and install the WSL2 kernel from [WSL2 kernel upgrade page](https://docs.microsoft.com/en-us/windows/wsl/wsl2-kernel).
8. Set the default WSL version to 2: `wsl --set-default-version 2` You may be prompted to upgrade the WSL2 kernel.
9. Install a WSL2 distro from the Microsoft Store. We recommend [Ubuntu](https://www.microsoft.com/store/productId/9NBLGGH4MSV6). (You do not have to log in to the Microsoft Store, just "X" out the dialog box requesting that.)
10. **Docker Desktop for Windows:** If you already have the latest Docker Desktop, configure it in the General Settings to use the WSL2-based engine. Otherwise install the latest Docker Desktop for Windows and select the WSL2-based engine (not legacy Hyper-V) when installing. Install via Chocolatey with `choco install docker-desktop` or it can be downloaded from [download.docker.com](https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe). Start Docker. It may prompt you to log out and log in again, or reboot.
11. Go to Docker Desktop settings > Resources > WSL integration > enable integration for your distro (now `docker` commands will be available from within your WSL2 distro).
12. Double-check in PowerShell: `wsl -l -v` should show three distros, and your Ubuntu should be the default. All three should be WSL version 2.
13. Double-check in Ubuntu (or your distro): `echo $CAROOT` should show something like `/mnt/c/Users/<you>/AppData/Local/mkcert`
14. Check that docker is working inside Ubuntu (or your distro): `docker ps`
15. Optional: If you prefer to use the *Windows* ddev instead of working inside WSL2, install it with `choco install -y ddev`. The Windows ddev works fine with the WSL2-based Docker engine.
16. Open the WSL2 terminal, for example `Ubuntu` from the Windows start menu.
17. Install Homebrew: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` (See [brew.sh](https://brew.sh/).)
18. Add brew to your path as prompted, for example, `echo 'eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)' >> ~/.profile && source ~/.profile`
19. `brew install gcc && brew install drud/ddev/ddev`
20. `sudo apt-get update && sudo apt-get install -y xdg-utils` to install the xdg-utils package that allows `ddev launch` to work.

That's it! You have now installed DDEV on WSL2. If you're using WSL2 for ddev (recommended), remember to run all `ddev` commands inside the WSL2 distro.
4. In an administrative PowerShell, run `mkcert -install` and answer the prompt allowing the installation of the Certificate Authority.
5. In an administrative PowerShell, run the command `setx CAROOT "$(mkcert -CAROOT)"; If ($Env:WSLENV -notlike "*CAROOT/up:*") { setx WSLENV "CAROOT/up:$Env:WSLENV" }`. This will set WSL2 to use the Certificate Authority installed on the Windows side.
6. In administrative PowerShell, run the command `wsl --install`. This will install WSL2 and Ubuntu for you. Reboot when this is done.
7. **Docker Desktop for Windows:** If you already have the latest Docker Desktop, configure it in the General Settings to use the WSL2-based engine. Otherwise install the latest Docker Desktop for Windows and select the WSL2-based engine (not legacy Hyper-V) when installing. Install via Chocolatey with `choco install docker-desktop` or it can be downloaded from [desktop.docker.com](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe). Start Docker. It may prompt you to log out and log in again, or reboot.
8. Go to Docker Desktop settings > Resources > WSL integration > enable integration for your distro (now `docker` commands will be available from within your WSL2 distro).
9. Double-check in PowerShell: `wsl -l -v` should show three distros, and your Ubuntu should be the default. All three should be WSL version 2.
10. Double-check in Ubuntu (or your distro): `echo $CAROOT` should show something like `/mnt/c/Users/<you>/AppData/Local/mkcert`
11. Check that docker is working inside Ubuntu (or your distro): `docker ps`
12. Optional: If you prefer to use the *traditional Windows* ddev instead of working inside WSL2, install it with `choco install -y ddev`. The Windows ddev works fine with the WSL2-based Docker engine. However, the WSL2 ddev setup is vastly preferable and at least 10 times as fast. Support for the traditional Windows approach will eventually be dropped.
13. Open the WSL2 terminal, for example `Ubuntu` from the Windows start menu.
14. Install Homebrew: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` (See [brew.sh](https://brew.sh/).)
15. Add brew to your path as prompted:, `echo 'eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)' >> ~/.profile && source ~/.profile`
16. `brew install gcc && brew install drud/ddev/ddev`
17. `sudo apt-get update && sudo apt-get install -y xdg-utils` to install the xdg-utils package that allows `ddev launch` to work.

That's it! You have now installed DDEV on WSL2. If you're using WSL2 for DDEV (recommended), remember to run all `ddev` commands inside the WSL2 distro.

**Make sure you put your projects in the Linux filesystem (e.g. /home/<your_username>), _not_ in the Windows filesystem (/mnt/c), because you'll get vastly superior performance on the Linux filesystem.**

Expand Down

0 comments on commit 1574b48

Please sign in to comment.