Setup Drupal, Lando, XDebug3 and WSL 2 on Windows 10 in \\wsl$ folder.

10.5.2021 / Revised blog post: The latest PHPStorm version supports indexing and file listener directly on the WSL folder \\wsl$\<Distro Name>. No need for mutagen.io anymore.

For years, I'm using DrupalVM and Vagrant on my Windows machine combined with Vagrant WinNFSd. It worked well, but it was painfully slow. composer update took minutes on large projects and every page load was slow.

I also used WSL 1, but accessing files from an NTFS drive under /mnt/c/docs was slow.

By the end of May 2020, Microsoft started distributing the Windows 10 2004 update. This was the first release, where WSL 2 (Windows Subsystem Linux) was officially available as a part of Windows 10. WSL 2 is a new architecture that completely changes how Linux distributions interact with Windows. It's basically a native Linux kernel in Windows 10. The goal is to increase the file system performance and adding full system call compatibility.

The best feature of WSL 2 is the fact, that this is the new de facto-standard backend for Docker Desktop on Windows. Docker Desktop uses the dynamic memory allocation feature in WSL 2 to greatly improve the resource consumption. This means, Docker Desktop only uses the required amount of CPU and memory resources it needs, while enabling CPU and memory-intensive tasks such as building a container to run way faster.

Additionally, with WSL 2, the time required to start a Docker daemon after a cold start is significantly faster. It takes less than 10 seconds to start the Docker daemon compared to almost a minute in the previous version of Docker Desktop.

I combined these new technologies with Lando and created a perfect developer setup for any PHP / Symfony / Drupal-driven development stack. In order to have faster indexing and file change listener in your IDE, you need a PHPStorm Version later thatn 2021.1.

Install WSL 2 on Windows 10

Follow the official documentation to install and enable WSL 2:
https://docs.microsoft.com/en-us/windows/wsl/install-win10

At some point, you will have to enable Hyper-V and set WSL 2 as your default version:
wsl --set-default-version 2

Install the Distro Ubuntu from the Microsoft Store

Open the Microsoft Store and install Ubuntu.

The first time you launch a newly installed Linux distribution, a console window will open and you'll be asked to wait for a minute or two for files to decompress and be stored on your PC. All future launches should take less than a second.

If you already have a WSL 1 distro you can upgrade it:
wsl --list --verbose
wsl --set-version <distribution name> <versionNumber>

Install Docker Desktop on Windows

Next, install Docker Desktop on WINDOWS!. By the time of writing, the current version was 3.3.3. Download it here.

Be careful!

There are a few tutorials online, that claim that you have to install docker inside your Linux distribution. This is wrong. You have to install Docker Desktop on Windows!

Install Lando > 3.0.26 inside your Ubuntu distro

Now we will install Lando inside our brand new WSL 2 distro "Ubuntu". This is a bit tricky, because docker-ce is a hard dependency of the package. But the official documentation has a solution for that.
Use at least Lando 3.0.26 found on github.
https://github.com/lando/lando/releases/download/v3.0.26/lando-v3.0.26.deb
dpkg -i --ignore-depends=docker-ce lando-v3.0.26.deb

To fix the package manager / apt-get you have to remove the Lando Package from /var/lib/dpkg/status.
nano /var/lib/dpkg/status, search for Lando and remove the entry from the file. Done.

Integrate Lando in an existing Drupal project

I assume, that you already have a running project and want to integrate it with Lando and WSL 2. The most important thing is, that your files have to life inside your Ubuntu distro e.g. /home/username/projects and not on /mnt/c/ something. Inside your Ubuntu distro, you can profit from an EXT4 file system and native file system speed
Go ahead and checkout your project from Git inside your home folder:
/home/username/projects/yourproject

Add a .lando.yml file.

Please refer to the official Lando documentation. Attached you will find my optimized recipe for Drupal 8 with Solr. I also added lando/php.ini with some optimized PHP variables.

name: demo
recipe: drupal8
config:
  webroot: docroot
  php: '7.4'
  xdebug: 'false'
  composer_version: "2.0.12"
  config:
    php: lando/php.ini

proxy:
  fulltext:
    - admin.solr.fulltext.lndo.site:8983

services:
  appserver:
    build:
      - composer install
    xdebug: true
    overrides:
      environment:
        # support debugging Drush with XDEBUG.
        PHP_IDE_CONFIG: "serverName=appserver"
        LANDO_HOST_IP: "host.docker.internal"
        XDEBUG_CONFIG: "remote_enable=1 remote_host=host.docker.internal"
        DRUSH_OPTIONS_URI: "https://demo.lndo.site"

  database:
    # You can connect externally via "external_connection" info from `lando info`.
    portforward: true
    creds:
      # These credentials are used only for this specific instance.
      # You can use the same credentials for each Lando site.
      user: drupal
      password: drupal
      database: drupal

  fulltext:
    type: solr:8.4
    portforward: true
    core: fulltext_index
    config:
      dir: solr/conf

  memcached:
    type: memcached
    portforward: false
    mem: 256

tooling:
  phpunit-local:
    service: appserver
    description: Runs phpunit with config at web/sites/default/local.phpunit.xml
    cmd: /app/vendor/bin/phpunit -v -c /app/web/sites/default/local.phpunit.xml
  xdebug-on:
    service: appserver
    description: Enable xdebug for apache.
    cmd: docker-php-ext-enable xdebug && /etc/init.d/apache2 reload
    user: root
  xdebug-off:
    service: appserver
    description: Disable xdebug for apache.
    cmd: rm /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && /etc/init.d/apache2 reload
    user: root

Add some necessary XDebug 3 settings in your custom php.ini

Under /lando/php.ini

memory_limit = 512M
xdebug.max_nesting_level = 256
xdebug.show_exception_trace = 0
xdebug.collect_params = 0
xdebug.client_host = ${LANDO_HOST_IP}
xdebug.client_port = 9003
xdebug.log = /tmp/xdebug.log
xdebug.mode = debug
xdebug.start_with_request = yes
# Very important, else the IP is overriden.
xdebug.discover_client_host = 0
# Add error log file to avoid spam console messages.
error_log = /tmp/php_error.log

Build your Lando project and start the docker container

Run lando start to spin up your containers and see if everything goes green.

Edit project files with PHPStorm / VisualStudio Code

Maybe you asked yourself: How can I edit my files, if they are inside my distro?

Microsoft added the \\wsl$\<Distro Name> file share. The performance while accessing this folder is quite slow but PHPStorm and also VisualStudio Code put a lot of effort to make it as convenient as possible. The initial indexing is usually slow if you have a lot of file in your project. Upcoming PHPStorm version will have an indexer that will run inside WSL2 to make the process faster.

There is no need to use mutagen.io anymore, as PHPStorm fixed all remaining issues when using a project on the \\wsl$\<Distro Name> file share.

How to use a git UI client, that is NOT slow on WSL2?

I usually use a Git UI Client. But on the \\wsl$\<Distro Name> file share it is almost unusable slow. As a workaround, you can install a bash git wrapper and execute the git inside wsl using the wslgit.exe provided here:
WSLGit

Currently I'm using the paid version of Fork. There you can select your wslgit.exe in the settings. I also tested it with SourceTreeApp. With Git Tower it's a bit shaky.

Final thoughts

Enjoy your blazing fast development environment, edit your files in your favourite IDE on Windows and thank all the maintainers of the involved Open Source projects.