DDEV WSL2

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

Wow, that is amazingly awesome! Absolutely top-knotch.

1. This is missing the super-important wsl --set-default-version 2, which should be done right after WSL is installed. I recently went through a new clean setup and missed this and accidentally set up a wsl1, and the conversion to 2 was so painful I gave up and started over.
2. You have stuff in the right order, but it's super important to install Ubuntu before Docker, otherwise one of Docker's VMs becomes the default VM.
3. Emphasize that projects should be in the WSL2 home directory, not in /mnt/c, because you lose all the performance if you try to work in the Windows filesystem.
4. Add the apt-get update on places you do apt-get install, remembering that many people who will try this know nothing about Debian/Ubuntu. They'll be refugees from the Windows side seeking performance improvement.
5. Add that Win10 Home is now supported and works fine just like this. (Perhaps mention that Docker Toolbox will be deprecated, mostly because we need the testing resources elsewhere)
6. I think for PHPStorm we should just say "For now, install PHPStorm in WSL2", since it's just too hard to use Jetbrains stuff in WSL2 right now. Very frustrating for me. It requires an X server like X410, but isn't hard. But I think you'd get too far off in the weeds in this article. Say that we'll do a followup with PHPStorm-in-wsl2 info, and we're hoping for more from Jetbrains.
7. I think it would be better if you used Ubuntu 20.04, almost exactly the same. But apt-get install docker.io docker-compose actually works with usable versions! It also makes the article seem relevant for longer as well. (Edited: You don't have to install docker or docker-compose with current docker, it does it for you; that may make 20.04 a red herring, but it still will make the article relevant longer)
8. Mention that nfs_mount_enabled is not useful because native Linux is so blazingly fast.

Followup tasks:

• How to use PHPStorm/Chrome installed inside WSL2
• X11: x410: export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0 and needs to "allow public access", and shared clipboard. (link)

Thanks for the feedback @rfay! Will update the article later today 👍

@rfay have updated the above gist based on your feedback, should be complete now 🎉

Looks great, just a couple of nits.

• Please add an outline at the top (right before "install wsl2") so that people can see a bulleted list of what they're going to do.
• There are a couple of places and one image that refer to Ubuntu 18.04 although you changed the general verbiage to 20.04.

You can do that, or we'll be happy to do that too. This is outstanding.

@rfay Fixed! Thanks for the feedback

I wish I had read this before I spilled too many hours on the non-WSL2 DDEV I was using. The difference is astounding, and must if you can move to WSL2.

Howdy @dennisameling! Randy and I got your post queued for publication next week (Monday is a US holiday) on ddev.com. Could you please review this PDF of the post, especially for your bio at the beginning, and let me know if there are any changes you would like made?
Thanks very much again for putting this together!

@ekl1773 sorry for the late response! Looks good to me 🚀 thanks!! 😊

@dennisameling You are LIVE on ddev.com 🥳 (edit: correct link!) https://ddev.com/ddev-local/ddev-wsl2-getting-started/
Thank you!

@ekl1773 yay! Thanks! 🎉

There seems to be issue with the images on the live website. The aspect radio is off.

I logged an issue on ddev/ddev#3410 but it doesn't feel like the right place. I'm commenting here in the hope that the right people see it and fix the otherwise excellent article!