Drupal + WSL2 + Lando + PHPStorm + Xdebug

Before you get started, make sure your requirements are met. I'll be using the most up-to-date versions of software--unless otherwise stated--as of the time of this page being published.

Requirements

Things you'll need before getting started.

• Windows 10+ (I'm using Win11)
  • Make sure it's fully updated

Will be installing

Things you'll be installing during this process.

• WSL2
• Ubuntu 22.04
• Lando
• PHPStorm

Recommended

• Terminal app - I think this is now included in Win11

Install WSL2

1. Open Terminal (or Windows PowerShell) as an Administrator
2. Enter the command `wsl --install` to install WSL2
   1. NOTE: "Windows Subsystem for Linux" is unchecked in Windows Features.
3. Restart your machine

Configure Ubuntu

1. When you restart and open Terminal (or, you may be greeted with it after restart), you'll see a dialog to install Ubuntu.
2. Enter your username and a password (don't forget the password.)
3. Install certain packages on Ubuntu
   1. `sudo apt update -y`
   2. `sudo apt upgrade -y`

Install Composer

Once you have Lando installed later, you'll be able to run all composer commands in the Lando containers using `lando composer ...`. But, in case you want to run Composer commands from anywhere in WSL (such as when installing a new Drupal site), you'll need to install it.

1. `sudo apt install php-cli php-mbstring php-xml php-gd unzip`
2. `curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php`
3. `HASH=`curl -sS https://composer.github.io/installer.sig``
   1. Verify the hash of the downloaded PHP composer script with the signatures present at the official page
4. `php -r "if (hash_file('SHA384', '/tmp/composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"`
   1. Validate if the PHP Composer installer can be safely executed or not
5. `sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer`
   1. Install PHP Composer

Install Docker Desktop

1. Download Docker Desktop for Windows and install it
2. Verify that General -> Use the WSL 2 based engine is checked.
   1. Older versions may read it as Use WSL 2 instead of Hyper-V (recommended)
3. Look under Resources -> WSL Integration
   1. If starting from scratch with WSL, then your Ubuntu image should be your default, and Enable integration with my default WSL distro should have you covered, but jsut to be sure, you may want to check it on here

Get your Project Files

At this point, you'll want to add the files for your project into WSL.

You can do it from within the terminal using git/wget/however you choose, or you can navigate the file explorer to `\\wsl$` and find a spot for it.

For the purposes of this tutorial, I'm going to install a fresh copy of D9 using composer. If you'd like to do the same, navigate to where you want, and enter the following command:

composer create-project drupal/recommended-project:^9 drupal9
composer install

1. Go to the download page for the latest version of Lando; as of this writing, that would be 3.11.0
2. Copy the download link for the appropriate version of Lando; for me, it's the Debian.
3. Open the terminal (if not in the WSL CLI, type wsl)
4. Install Lando
   1. `wget https://github.com/lando/lando/releases/download/v3.11.0/lando-x64-v3.11.0.deb`
   2. `sudo dpkg -i --ignore-depends=docker-ce the_lando_package.deb`
      1. You'll notice the --ignore-depends; Lando looks for docker-ce and won't see the docker installed on the Windows side. But, this will work.

5. Fix the dependency issue (for now)

   1. Open the /var/lib/dpkg/status file and go to the lando section
   2. Change Depends: iptables, procps, docker-ce to Depends: iptables, procps
   3. Unfornuately, this will be something you have to do every time yo update Lando

    

1. Follow Lando config setup (php.ini and xdebug stuff) at https://www.liip.ch/en/blog/setup-drupal-and-lando-with-wsl2-on-windows

My preferred method is to first install the JetBrains toolbox, then install PHPStorm from there.

When you open PHPStorm, and go to open a project, navigate to your project on the `\\wsl$` network drive.

Note: Another way to go about this is to select WSL. It will install PHPStorm within WSL, but you'll be connecting to it through PHPStorm in Windows through, what JetBrains calls, their "gateway". The idea is to get the speed of not dealing with the differing filesystems, and the performance of running PHPStorm locally instead of inside the WSL VM. For me though, just running PHPStorm in Windows and having it use the files in the \\wsl$ drive is plenty fine enough, and doesn't involve any gateway connection issues, which I seemed to get from time to time.

Start Lando

Navigate to your project within WSL. If you don't have a .lando.yml file in your project yet, run `lando init`, and follow the prompts. I'd recommend the following:

$ lando init
? From where should we get your app's codebase? current working directory
? What recipe do you want to use? drupal9
? Where is your webroot relative to the init destination? web
? What do you want to call this app? drupal

Run  `lando start`

You should get something that looks like this:
 

   ___                      __        __        __     __        ______
  / _ )___  ___  __ _  ___ / /  ___ _/ /_____ _/ /__ _/ /_____ _/ / / /
 / _  / _ \/ _ \/  ' \(_-</ _ \/ _ `/  '_/ _ `/ / _ `/  '_/ _ `/_/_/_/ 
/____/\___/\___/_/_/_/___/_//_/\_,_/_/\_\\_,_/_/\_,_/_/\_\\_,_(_|_|_)  
                                                                       

Your app has started up correctly.
Here are some vitals:

 NAME            drupal                            
 LOCATION        /home/cferagotti/projects/drupal9 
 SERVICES        appserver, database               
 APPSERVER URLS  https://localhost:53608           
                 http://localhost:53609            
                 http://drupal.lndo.site/          
                 https://drupal.lndo.site/ 

Clicking on the https://drupal.lndo.site/ link should take you to a Drupal install. Run through the install, setting the Lando drupal9 recipe defaults for the database connection as:

Database name: drupal9
Database username: drupal9
Database password: drupal9
Advanced Settings -> Host: database

Then follow the rest of the D9 setup as you would choose otherwise, and you'll have a functioning Drupal 9 site.

Adding to the Lando file

- Add the stuff here

Didn't seem like I actually needed to set up an y kind of server on PHPStorm's end? I think when I entered https://cf.lndo.site as the address on the Xdebug verify tool, it added it.

These are just some things I'd recommend...

• Install ZSH/OhMyZSH
• Install PowerLevel10k

1. Install ZSH/OhMyZSH
   1. Sudo apt install zsh
   2. sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
2. Install powerlevel10k
   1. git clone https://github.com/romkatv/powerlevel10k.git $ZSH_CUSTOM/themes/powerlevel10k
   2. Add the following to ~/.zshrc
      1. ZSH_THEME="powerlevel10k/powerlevel10k"

Lando's Certificate Authority

This should probably be placed in the Lando section, the problem is that you can't do it/the CA file won't exist until after you first start a Lando project.

If you don't want to be warned by your browser about the sketchkiness of the SSL of your local site every time you go to it, open PowerShell as an admin and run the following command, replacing <yourusername> with the username you created in WSL:

certutil -addstore -f "ROOT" \\wsl.localhost\Ubuntu\home\<yourusername>\.lando\certs\lndo.site.pem

mySQL 8.0+

There seems to be a compatibility issue with Lando and MySQL 8.0+ that they don't seem to be in any real hurry to fix. There a couple work arounds, but I tend to use the one that uses a quick and dirty Lando file edit.

WSL Reporting Docker not started and Attempts to start fail

Not really sure what's causing this, but what seems to fix it (aside from a full system restart) is to run `wsl --shutdown` in Windows' terminal, then restart Docker Desktop, followed by a lando start.