dennisameling/DDEV WSL2.md

## DDEV WSL2.md

      
    Raw
  

              DDEV WSL2.md
            
          
    DDEV ❤ WSL2: getting started

Now that WSL2 is about to become generally available as part of the Windows 10 May 2020 (2004) update, it's time to look into running DDEV on WSL2!
All Windows 10 editions (including Windows 10 Home) support WSL2. Docker Toolbox support for DDEV will be deprecated, as we'll move testing capacity towards WSL2. 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 🚀
Outline


Install WSL2
Install Docker
Install DDEV

Prepare SSL certificate (mkcert)
Installing the Linux version of DDEV


Using DDEV
(optional) DDEV launch command
(optional) Working with IDEs

VS Code

XDebug in VS Code


PhpStorm


Install WSL2

First, we'll have to install WSL2 on our machine. You can follow Microsoft's official instructions to do this. Don't forget to set the default WSL version to WSL2! wsl --set-default-version  2
In this example, we'll be using Ubuntu 20.04, which you can download from the Microsoft Store.
Make sure to install Ubuntu (or any other distro) before installing Docker, so that Ubuntu becomes the default WSL distro.
Install Docker

Next up is Docker Desktop, which uses the WSL2 backend by default since version 2.3.0.2. Go ahead and download Docker Desktop for Windows from Docker Hub.
When you're done, go to Docker Desktop settings > Resources > WSL integration > enable integration for your distro (now docker commands will be available from within your WSL2 distro):

Install DDEV

We're ready to install DDEV! Please note that there's one gotcha here: we'll install DDEV for Linux, not for Windows! This is because you will get the best performance when working in the Linux filesystem. Don't go back and forth between the regular Windows side and WSL2. This is also Microsoft's recommended approach.
To make things more visual, let's take a look at the image below. Docker + DDEV will basically be running in WSL2 and expose ports to Windows. This way, you benefit from very good (Linux-based) performance while having the convenience to access your DDEV sites from within Windows.
Make sure you put your projects in the Linux filesystem (e.g. /home/LINUX_USERNAME), not in the Windows filesystem (/mnt/c), for a much better performance.

Prepare SSL certificate (mkcert)


Install Chocolatey on Windows: https://chocolatey.org/install
Open a PowerShell terminal with administrator rights and run choco install mkcert
Run mkcert -install. Your certificates are installed in %localappdata%\mkcert, we'll need these later on.
Open the Ubuntu 20.04 terminal from the Windows start menu.
Run export CAROOT=/mnt/c/Users/YOUR_WINDOWS_USERNAME/AppData/Local/mkcert. This will make sure that mkcert on Linux uses your Windows certificates when issuing SSL certificates, so you don't get SSL warnings in your browser on Windows.
Run echo 'export CAROOT=/mnt/c/Users/YOUR_WINDOWS_USERNAME/AppData/Local/mkcert' >> ~/.profile to store this in your profile for future sessions.

Installing the Linux version of DDEV


Open the Ubuntu 20.04 terminal from the Windows start menu.
Follow the installation instructions for Linux/MacOS as provided in the DDEV docs. After installation, run mkcert -install and you'll notice that mkcert will use your Windows CA certificates 🚀:

Using the local CA at "/mnt/c/Users/YOUR_WINDOWS_USERNAME/AppData/Local/mkcert"


That's it! You have now installed DDEV on WSL2 🎉 Remember to run all ddev commands in your Ubuntu/WSL2 terminal, not in PowerShell/Command Prompt.
Using DDEV

Let's try to get a DDEV site up and running using the WordPress Quickstart. The first time it might take a while for the database/webserver/etc. images to download, but after that you can start new instances lightning-fast ⚡
When navigating to https://my-wp-bedrock-site.ddev.site, we are presented with the WordPress installation screen:

Fantastic! Even the SSL certificate works as expected. You're now ready to start developing with DDEV on WSL2 🚀
(optional) DDEV launch command

If you want to use the ddev launch command, you'll need to install xdg-utils with sudo apt-get update && sudo apt-get install xdg-utils. After that, when you run ddev launch within a DDEV project directory, the site will launch in your default browser on Windows. Pretty awesome, right?
(optional) Working with IDEs

VS Code

VS Code has a special integration with WSL2 in its Remote Development extension pack. This allows you to directly work in the Linux filesystem from within your IDE.


Install VS Code + the Remote Development extension pack


Open VS Code, connect to your WSL2 distro. You can now access the file system of your Linux distro from within Windows ✨


If you open a terminal by going to Terminal in the top menu > New terminal, you are immediately in the WSL2 environment and can run commands over there, like ddev start.


XDebug in VS Code

If you want to use XDebug in VS Code, make sure you set the hostname to 0.0.0.0 and set the correct pathMappings for DDEV. This way, you can use XDebug like you're used to:
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "hostname": "0.0.0.0",
            "port": 9000,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}"
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}
PhpStorm

PhpStorm supports WSL2 since its 2019.3 release, but the experience is far from ideal. For now, we recommend installing PhpStork wit, but that falls outside the scope of this article. We'll follow up with a "PhpStorm in WSL2" article later, and we're hoping that JetBrains will provide better support for WSL2 in the future. the fi