Drupal Development in Windows using WSL2, Ubuntu, and Lando

Tags
PHP Drupal Docker WSL Lando

This development methodology allows a developer to develop completely within WSL and helps overcome severe performance issues with latency that exists between the WSL file system and the Windows file system when running docker. Effectively, everything, can take place inside of the WSL2 virtual machine. Everything means everything, this includes but is not limited to: editing code via an IDE, testing the site in a web browser, and even creating Lando Docker containers. (Yes, docker containers running inside of WSL2, fully independent of host Windows operating system.)

Prerequisites

These instructions require an untouched installation of WSL and Docker. At no point should docker have been installed in Windows prior to this. If it has, Docker should be fully uninstalled including the removal of all WSL distributions related to Docker.

Preparing Your System

Preparing a system that has already had Lando installed in Windows requires completion:

  1. Docker be fully uninstalled using its Windows uninstaller.
  2. All WSL distributions be terminated and unregistered.

  3. Get a list of all WSL Distributions on your system.

    wsl --list

    Note: One of these might be marked with (Default) at the end, be aware that this is not part of the name for the WSL Distribution. E.g. Ubuntu (Default) is just called Ubuntu.

    Note: When you run this command you are not presented with a list of WSL Distributions, you likely do not yet have WSL installed. Continue to the next section called WSL Setup.

  4. For every item in the list that appears run the following commands.

    wsl --terminate {Distribution Name}
    wsl --unregister {Distribution Name}

    Note: These commands will shut down and delete, but not necessarily uninstall, each WSL Linux distribution. Consider going through your installed apps (Settings > Apps) and uninstalling all WSL Linux distributions you find there. Afterwards run wsl --uninstall, and restarting your computer to make sure everything is removed.

WSL Setup

Install via PowerShell

  1. In PowerShell as an admin run the following command:

    wsl --install -d Ubuntu-24.04
  2. If you were not prompted to reboot you should see a message indicating that Ubuntu is currently being installed. Shortly after you will be prompted to create a username and password. Provide the requested information.

  3. If you were prompted to reboot your computer. This can also be done in PowerShell

    shutdown /r /p
    • Upon rebooting and logging into Windows, a Command Prompt window will open with a message indicating that Ubuntu is currently being installed. Shortly after you will be prompted to create a username and password. Provide the requested information.

Accessing WSL

When WSL distributions are installed, they show up and can be accessed in multiple difference places.

  • In Windows Terminal, a profile will automatically be added allowing you to open a new tab that will display the command line for the WSL distribution instance.
  • In PowerShell or any other Windows command prompt user interface you can run the command wsl, if there is more than one WSL distribution on your system, run the command that includes the name of the distribution wsl -d Ubuntu-22.04. This will display the command line for the WSL distribution instance.
  • In the Start menu, you will find the WSL distribution by name in the All apps section, clicking on it will display the command line for the WSL distribution instance.
  • To access files in WSL, open a File Explorer window and place \\WSL$ into the address bar at the top. This will allow you to access all of the files in your WSL distribution instance.
    • This same path can be used for IDEs installed in Windows.

Verify WSL has DNS Connectivity

Some systems have an issue where DNS is routed through a system in Windows which prevents WSL from being able to access sites on the internet by domain name. This interferes with the ability to set up the required software on WSL.

  1. Verify that you have DNS-based connectivity.

    • In Windows Terminal, in the Ubuntu tab, run the command:

      ping google.com

      If an error indicating Temporary failure in name resolution is displayed, continue with this step to resolve this issue. If you see successful pings you do not need to continue with this list.

  2. Modify /etc/wsl.conf to include the following:

    [network]
generateResolvConf=false

  3. Close the WSL Ubuntu tab and run the following command in PowerShell:

    wsl --shutdown

    • Alternatively from within WSL you can run:

      sudo reboot

  4. Open a new WSL Ubuntu tab modify /etc/resolv.conf to include the following:

    nameserver 1.1.1.1

    Note: 1.1.1.1 is Cloudflare's public DNS server. If there is DNS-based security software on your system this will subvert it for all DNS requests inside of WSL.

  5. Close the WSL Ubuntu tab and run the following command in PowerShell to reboot the WSL instance:

    wsl --shutdown

  6. Open a new WSL Ubuntu tab and run the following command:

    ping google.com

    If successful you should start seeing indication of connectivity and DNS resolution to IP addresses in the output. Press Ctrl + C to interrupt the output. You're good to continue with the setup process.

Lando and Docker Setup

The following section should be taking place exclusively inside of the WSL command line unless otherwise stated. The only exception being looking stuff up in a web browser as you will not be able to do this in WSL just yet.

When running apt-get against a downloaded file, you will likely see an error indicating that the _apt user is unable to access the file that software is being installed from. For example:

N: Download is performed unsandboxed as root as file '/home/user/lando-x64-v3.20.4.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

This is normal, and should be ignored as it does not disrupt the installation process.

Ensure the WSL Distro is up to Date

Before starting we need to make sure that everything in the Linux Distribution is up to date. To do this run the commands:

sudo apt-get update
sudo apt-get dist-upgrade

Install Docker

  1. Run the commands

    curl -fsSL https://get.docker.com -o install-docker.sh
sudo sh install-docker.sh

    When you run this command inside of WSL, you will receive a recommendation from Docker's installer urging you to install Docker Desktop for Windows. We do not want to do this for performance reasons. Ignore this warning and wait for the setup process to complete.

    • Run the command dockerd-rootless-setuptool.sh install
    • If prompted run the command sudo apt-get install -y uidmap

  2. Add the user to the docker group by running the command

    sudo usermod -aG docker $USER

  3. Restart the WSL distribution.

    sudo reboot

Install Lando

Run the following command

/bin/bash -c "$(curl -fsSL https://get.lando.dev/setup-lando.sh)"

Prevent Lando on WSL Ubuntu from Installing Docker Desktop for Windows

As of v3.23.21, Lando will verify if Docker Desktop is installed whenever you run lando start. It will then try to and succeed in installing Docker Desktop for Windows from within WSL. Counterproductive to our goal given that we are trying to keep Docker for Windows out of the picture. To resolve this issue run the following command:

echo -e "setup:\n  buildEngine: false" > ~/.lando/config.yml

Use of this command assumes you have no existing global Lando configurations (i.e. a fresh install). It will overwrite the file at ~/.lando/config.yml. Should you already have customizations in your global Lando configuration, add the following lines instead:

setup:
  buildEngine: false

Starting Lando

With Lando now set up, you can clone your project into your WSL distribution instance's user's home directory and, if your project has a .lando.yml file, run lando start . If you don't have .lando.yml file in your project, you can use the lando init command to have Lando generate one for you.

Start Development

At this point, you have everything you need to begin development with Lando inside of WSL. When you run lando start from within WSL on your project, assuming it has a .lando.yml file, it should spin up as expected. Using a web browser in Windows, the URL that was provided by lando that ends in .lndo.site should work to access the site. If you want to use your IDE that is installed in Windows, you should be able to access project files through the \\WSL$ path in Windows.

There are a few things that do not work out of the box at this point including:

  • Breakpoint debugging will not work in Windows-based IDEs out of the box.

If these issues do not matter to you, you can stop here and start developing.

To overcome these issues, you can install all of the tools you use to develop sites within WSL so that they are running on the same virtual machine at the Lando instance.

WSL GUI Setup

This section is optional. If you are finding there are a large number of issues in using your IDE in Windows to modify files on the WSL's file system consider using GUI tools provided by WSL. These tools are effectively GUI applications running in WSL and shows up in your Windows Desktop as if they are part of Windows itself.

The following should be taking place exclusively inside of the WSL command line unless otherwise stated. The only exception being looking stuff up in a web browser as you will not be able to do this in WSL just yet.

When running apt-get against a downloaded file, you will likely see an error indicating that the _apt user is unable to access the file that software is being installed from. For example:

N: Download is performed unsandboxed as root as file '/home/user/lando-x64-v3.20.4.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

This is normal, and should be ignored as it does not disrupt the installation process.

Install a GUI Package

  1. Make sure Linux is up to date by running

    sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get install x11-apps

  2. Test to ensure the installation is successful:

    xeyes &
    • You should see a pair of eyes in a window on the screen when you move your cursor over the eyes, they should follow the cursor. Your WSL distribution instance is now set up to run GUI applications.

Install Chrome

Lando domains from any Lando instances inside of WLS should be accessible from within Windows. If for whatever reason this does not work, you should be able to view local Lando websites in web browsers that are running inside of your WSL distribution instance.

Installation Steps

  1. Run the following commands

    wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt-get install ./google-chrome-stable_current_amd64.deb

    Note: The above URL to the chrome installer assumes that you are using an X64 processor. If you are using an ARM-based processor you will need to find the correct URL to download chrome.

  2. Modify your .bashrc file to include an alias to chrome by running the command:

    echo -e "\nalias chrome='google-chrome &> /dev/null &'" >> ~/.bashrc

  3. After making the change to the .bashrc file, run the following to load the changes.

    source ~/.bashrc

Starting Google Chrome in WSL

Run the following command:

chrome

Note: Take a look how the border and title bar of the window appears different when being run in WSL compared to chrome running from Windows.

Note: When you run Google Chrome in the WSL distribution instance, any settings logins, cookies, etc. stay in the WSL distribution instance.

Optional: Install Visual Studio Code

Microsoft Recommends using the Windows version of VS Code to modify files inside of WSL. If there are a lot of files, this may lead to significant latency between Windows and WSL file systems. If latency is an issue you can ignore this recommendation and run VS Code as a WSL application.

Installation Steps

  1. Download Visual Studio Code using Google Chrome.

    1. Open Google Chrome in WSL run the command:

      chrome
    2. Use the Google Chrome window that will appear to download Visual Studio Code from https://code.visualstudio.com/download. Select the version that is compatible with Debian and Ubuntu whose extension ends in .deb and system architecture matches your own.
    3. The file should download to the ~/Downloads folder.

  2. Go to the downloads folder and install VSCode by running the commands.

    cd ~/Downloads
chmod 777 code_1.83.1-1-1696982868_amd64.deb
sudo apt-get install ./code_1.83.1-1-1696982868_amd64.deb

    Note: The filenames used in the above commands will likely be different as new versions of Visual Studio Code come out. In the apt-get command, make sure the filename provided to the command matches the installer downloaded.

  3. Modify your .bashrc file to prevent Visual Studio Code from prompting you to install it in Windows instead of WSL by running the following:

    echo -e "\nexport DONT_PROMPT_WSL_INSTALL=1" >> ~/.bashrc

  4. After making the change to the .bashrc file, run the following to load the changes.

    source ~/.bashrc

Starting Visual Studio Code

Run the following command:

code

Optional: Install PhpStorm

Microsoft Recommends using the Windows version of IDEs to modify files inside of WSL. (See https://www.jetbrains.com/help/phpstorm/how-to-use-wsl-development-environment-in-product.html for more information on how to do this.) If there are a lot of files, this may lead to significant latency between Windows and WSL file systems. If latency is an issue you can ignore the recommendations and run PhpStorm as a WSL application.

Installation Steps

  1. Download PHP Storm using Google Chrome.

    1. To open Google Chrome run the command:

      chrome
    2. Use the Google Chrome window that will appear to download PHP Storm from https://www.jetbrains.com/phpstorm/download/#section=linux. Select the version that is compatible with Linux and your system architecture.
      • The file should download to ~/Downloads

  2. Go to the downloads folder, and extract the archive by running:

    cd ~/Downloads && mkdir -p ~/Applications && tar -zxvf PhpStorm-2023.2.3.tar.gz -C ~/Applications

    Note: In the above command, the archive will be exported to the ~/Applications directory in a directory called something like PhpStorm-232.10072.32, pay attention to file names as they likely will have changed since this documentation was written and is required for the next step

  3. Modify your .bashrc file to include an alias to PhpStorm running the following command (but only after you read the note immediately following it.)

    echo -e "\nalias phpstorm='~/Applications/PhpStorm-232.10072.32/bin/phpstorm.sh &> /dev/null &'" >> ~/.bashrc

    IMPORTANT: Before running this command, be sure that the above path resolves to an actual file called phpstorm.sh. Ensure that the PhpStorm-* directory name is also correct before running the command.

  4. After making the change to the .bashrc file, run the following to load the changes.

    source ~/.bashrc

NOTE: PhpStorm's licencing enforcement will scan the network you are on looking for other instances of PhpStorm running which are licensed to you. This means you will have to close the instance in Windows first.

Starting PhpStorm

Run the following command:

phpstorm

Starting Development Tools in WSL

Development requires the starting of the lando container, Google Chrome and Visual Studio Code (or other IDE) directly within WSL by running these commands.

lando start
chrome
code

NOTE: This command will start Visual Studio Code if it was installed, switch out code for whatever other command was set up for your IDE of choice.