DDEV ❤️ WSL2: getting started

DDEV By

Docker, DDEV, WSL2 Diagram

This is a guest post from web developer and open source contributor Dennis Ameling, owner of fits4all. Dennis also contributed this guide to the DDEV-Local documentation! Find out more about Dennis.

Note: The current instructions for WSL2 setup are in the DDEV docs and have been refined over the years.

Now that WSL2 is generally available as part of the Windows 10 May 2020 (2004) update, it’s time to look into running DDEV-Local on WSL2!

Wait, what is “WSL” anyway? It stands for the “Windows Subsystem for Linux”, and in version 2 it’s a full-powered implementation of Linux inside Windows. Read more in the WSL Documentation and WSL2 FAQ.

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

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.

Double-check to make sure that you have installed using WSL version 2: wsl -l -v should show your distro as version 2.

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 vastly superior performance. You’ll be very, very disappointed if you put them on /mnt/c.

Prepare SSL certificate (mkcert)

  • Install Chocolatey on Windows: https://chocolatey.org/install
  • Open a PowerShell windows with administrator rights and run choco install mkcert
  • Run mkcert -install.
  • Run setx CAROOT "$(mkcert -CAROOT)"; If ($Env:WSLENV -notlike "*CAROOT*") { setx WSLENV "CAROOT/up:$Env:WSLENV" } – this will set the CAROOT environment variable on the WSL2 side to point to the Windows CAROOT, so your Windows browser can trust sites running in WSL2.

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 in the Ubuntu terminal and you should see 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 ?

DDEV launch command (optional)

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?

Working with IDEs (optional)

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.

  • 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 not fine-tuned yet. There are two ways to use it – you can use it as a Windows app or use the Linux version of PHPStorm inside WSL2. We’ve got it written up for you in DDEV-Local and PHPStorm Debugging with WSL2.

Resources

Share this post: