Setup a Laravel development environemnt on Windows with WSL2

I've been on a journey of finding the perfect operating system to fit all my needs, In the past year I've used MacOS, Ubuntu and Windows on different machines, and as with everything, there're pros and cons to each OS, and I would always find some limitation in each, I like my devices to be battle ready, I want to be able to web surf, game and develop web apps seamlessly on them and the last 2 were the cause for problems, if I didn't game then Linux or MacOS would've been perfect by themselves.

While web development is definitely doable on Windows, especially if you're using asp.net, I use PHP and Python and I am just used to bash/zsh and the *nix filesystem, as well as brew/apt and downloading exes and installing is much slower than sudo apt install x

WSL2

Enter WSL2; short for Windows Subsystems for Linux, a clever Linux Virtual Machine inside Windows with crazy optimizations to overcome the overhead of a regular VM.

You can install a wide variety of distributions, but for this guide I will be using Ubuntu which is the default, for a full list of supported distros, go here

WSL2 Prerequisites

You need windows 10 (minimum version 2004) or windows 11 (any version) to use WSL2, you can check your version by opening Run using:

⊞ Win (windows key) + R

and entering winver in the box and clicking ok

Also you need to enable virtualization in your BIOS (I didn't need to do anything in my case but you could)

It's different for a variety of reasons, Intel CPUs and AMD CPUs have different names for that feature, as well as each motherboard has a different BIOS so there's no standard way to finding it, search for your laptop model or if you're on desktop search for enable virtualization on your specific motherboard model and CPU.

Ubuntu installation

To install ubuntu, open powershell in administrator mode and run wsl --install it will take sometime and once done it will prompt you to create a new user for your Linux distro, once that's done it will ask for a reboot.

If anything freezes or gets stuck during installation you can just quit out of it using ctrl + c and then hard rebooting your device and trying again (Hold shift when clicking on restart)

If that's stuck as well, search for Turn windows features on or off and uncheck:

1. Windows subsystem for Linux
2. Virtual Machine Platform

And click ok

Voila! ubuntu is up and running on your device!

Windows terminal

Once installed you'll have a new terminal open with bash running in ubuntu, this is fantastic, however I find a better experience by using Windows terminal, which can open up CMD, PowerShell and even ubuntu terminals from the same place, it is available in the microsoft store

Development Environment

With ubuntu installed, we need to get our tools ready!

Git

Git is already installed on ubuntu, but if it isn't it's as simple as

sudo apt install git

Mysql

as with a normal ubuntu experience just use apt

sudo apt install mysql-server
sudo service mysql start
sudo mysql_secure_installation

You can use a DB visual tool installed in Windows to view your database, I use TablePlus, but it will be the same for others, simple create a new connection with the following details:

Host: 127.0.0.1

Port: 3306

Username: your username

Password: your Password

You might need to create a new user instead of using root for this, if you didnt do that, you can do so now:

Enter mysql

sudo mysql

And create a new user from there and use the credentials to access the database.

CREATE USER 'abed'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

PHP

Again standard experience, we need to add the PPA for PHP and installing PHP with the required extensions.

One thing to note is the version of PHP, depending on the distro the default PHP version will be different, so if you have a specific version in mind, use that version in the script, eg: if you want to install php 8 instead of the default you must replace all occurences of php with php8.0, so for fpm you'd use php8.0-fpm and so on.

sudo add-apt-repository ppa:ondrej/php 
sudo apt install php php-fpm php-mysql php-mbstring php-xml php-bcmath php-intl php-curl php-zip
sudo service php-fpm start

Check for installation using

php -v

Node

In most cases you'd have some sort of Node based dependencies like React or VueJS etc, You have a lot of options but i like use NVM which makes switching versions a lot easier if you need to.

You can specify which version you want to install, for me i needed v14, so I used nvm install v14, but you can get the latest by using nvm install node, more info here

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
nvm install node

Composer

Installing composer is just 4 commands, but since the hash is different everytime, you need to get the instructions for composer's website

IDE/Editor

You need to install your editor in Windows not WSL (although with WSL2 you can launch linux GUI apps!)

Your linux distro is in the file system and can be accessed in your files from windows directly, enter this path: \\wsl$ and you will find all your distros and you can navigate through them from there, you can also use this if your editor doesn't natively support WSL2.

I am going to use vscode, but other editors are viable, PHPStorm supports WSL2, more details here

In vscode install the WSL2 extension pack, and then simple open up your bash terminal and simply run code /path/to/app, this will install vscode server on WSL2 and open up your vscode with the directory you specified open, and now you're ready!

More details for vscode here

Laravel

With everything up and running, open an existing project or create a new one:

composer create-project laravel/laravel laravel-in-wsl

IMPORTANT NOTE: Don't install any dependencies, projects or apps outside of WSL2 unless you plan to use them on windows only, while you can techically create a laravel project in Windows, it will be exteremely slow, the only thing that we should have installed on windows is the IDE/Editor, everything else is installed in Linux on WSL2.

Then open the directory and perform the usual commands

composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve

In the environment variable, add your db connection normally using 127.0.0.1 as the host and the email and password for the user you created.

You'll notice that if you open up your browser to localhost:8000 in Windows you should see that your app is working!

I even wrote this guide in WSL2 and i can preview my gatsby project (which is this blog) the same way!

A few Gotchas

You might face some issues with your laravel application, I will list the issues I've faced and their solutions.

1. If you have an Inertia app with React, you might see very very slow load times, if you check your network it will attempt to retrieve a file http//localhost/js/bundle.js, but it will timeout, It's used for hot reloading and I couldn't get it to work, but the fix for the general slowness is to comment the line that requires that file in your app.blade.php file, more details here
2. If you're seeing slow internet while in WSL2 (while downloading apps for example) you can disable IPv6 for the WSL2 network adapter, check here
3. NEVER put any data outside of the WSL2 instance, this will cause a massive slowdown in the performance, make sure everything is within the instance and don't attempt to use repositories that are on windows