Setup LEMP for Laravel on Windows using WSL

Introduction
Install Windows Terminal
Install WSL Ubuntu
Install Nginx
Install MySQL
Install PHP, Composer and Xdebug
- Configs Extras
- Install Composer
Create a Laravel Application
Install Mailpit
Manage Multiple Laravel Applications and PHP Versions
Extras
References

Introduction

Finally, we can setup a true Linux, Nginx, MySQL and Php (LEMP) environment on our Windows machine using Windows Subsystem for Linux (WSL).

If you're a Linux or Mac user, but you're forced to use a Windows machine just like me, or, if you simply want to develop web applications on your Windows PC while still on a Linux or Unix-like environment without dual-booting, this guide is for you.

Why not just use XAMPP, WAMP or MAMP? Well, these are functional until they aren't. They are very clunky, they can't make your local projects look good with domains like ~~myproject.test~~.

Why not use Homestead? Well, I wished I did, until I gave up trying to make it work on my Windows PC.

Why not use Laragon? I do use Laragon! I love it. It's lightweight, configurable, gives beautiful local domains like ~~myproject.test~~ and also supports sharing your local project to the internet using Ngrok. But, it is still not a true Linux/Unix-like environment.

Install Windows Terminal

Install Windows Terminal from Microsoft Store: https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701

Install WSL Ubuntu

Windows Subsystem for Linux

For the complete documentation of WSL, visit docs.microsoft.com.

Enabling WSL

Make sure you have installed the following Windows Features:

Virtual Machine Platform
Windows Subsystem for Linux

You can install them either from the Turn Windows features on or off control panel (as depicted on the screenshot above), or using the following PowerShell (opened as Administrator) commands:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

After installing the features, restart your computer.

WSL2

And finally, open PowerShell and set your WSL version to 2 by default:

wsl.exe --set-default-version 2

Using WSL version 2 may be optional, but I've encountered a few issues with just WSL 1.

Installing Ubuntu on WSL

Ubuntu itself is installed from the Microsoft Store app. Open Microsoft Store, search for Ubuntu, and click Get and Install.

Installing Ubuntu from Powershell

Install

wsl.exe --list --online
wsl.exe --install Ubuntu-24.04
wsl.exe --list --verbose

Uninstall

wsl.exe --list --verbose
wsl.exe --shutdown
wsl.exe --unregister Ubuntu-24.04
wsl.exe --update

Common error

bcdedit /set hypervisorlaunchtype Auto

Once WSL Ubuntu is installed, open a new Ubuntu tab in Windows Terminal.

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username:
New password:
Retype new password:

Installation successful!

cd ~
sudo apt update

Install Nginx

sudo apt install nginx

To start, stop or restart Nginx, run:

sudo service nginx start
sudo service nginx stop
sudo service nginx restart

#> To check the status of a service or to check whether it is enabled
sudo systemctl status nginx
#> To start a service immediately
sudo systemctl start nginx
#> To stop a running service
sudo systemctl stop nginx
#> To restart a running service or to start it if it’s not already running
sudo systemctl restart nginx
#> To reload a service without interrupting its operation
sudo systemctl reload nginx
#> To enable the Nginx server to start automatically, you would run
sudo systemctl enable nginx
#> You can check to see if the service is indeed enabled by typing
sudo systemctl is-enabled nginx
#> Should you wish to prevent a service from starting automatically on boot, you can use
sudo systemctl disable nginx

Install MySQL

To install MySQL, run:

sudo apt install mysql-server

Configure MySQL

sudo service mysql stop
sudo usermod -d /var/lib/mysql mysql
sudo service mysql start
sudo mysql_secure_installation
    #> Validate password component: N
    #> New password: MyPassword
    #> Remove anonymous users: Y
    #> Disallow root login remotely: Y
    #> Remove test database and access to it: Y
    #> Reload privilege tables now: Y

The VALIDATE PASSWORD PLUGIN should be disabled only in your local environment, if you wish to set simple passwords such as “root”.

sudo mysql

mysql> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '123456';
mysql> FLUSH PRIVILEGES;
mysql> exit;

Connect to MySQL:

sudo mysql #> If username and password is not needed.

sudo mysql -u root -p #> If username and password is needed.

Inside MySQL, create a new database for our example Laravel application:

mysql> CREATE DATABASE laravel;
mysql> exit;

Connect Remote to MySQL:

mysql> CREATE USER 'ubuntu-wsl2'@'%' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'ubuntu-wsl2'@'%';
mysql> FLUSH PRIVILEGES;

If you encounter the error Can't connect to local MySQL server through socket '/run/mysqld/mysqld.sock', resolve it by following the solution at Stack Overflow:

sudo service mysql stop
sudo mkdir -p /var/run/mysqld
sudo chown mysql:mysql /var/run/mysqld
sudo mysql service start

To start, stop or restart MySQL, run:

sudo service mysql start
sudo service mysql stop
sudo service mysql restart

Install PHP, Composer and Xdebug

To install PHP and the recommended extensions, run:

sudo apt install php8.3 php8.3-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip,xdebug}
php --version

To install zip and unzip, run:

sudo apt install zip unzip

To start, stop or restart PHP, run:

sudo service php8.3-fpm start
sudo service php8.3 stop
sudo service php8.3 restart

Configs Extras

Remove Nginx and PHP

sudo apt remove --purge nginx*
sudo apt remove --purge php8.*
sudo apt autoremove
sudo apt update

Install Composer

To create a new Laravel project, it will be useful to have Composer tool installed globally.

curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
HASH=`curl -sS https://composer.github.io/installer.sig`
echo $HASH
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;"
sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
composer --version

Create a Laravel Application

Laravel projects

cd /var/www/html

Create a new Laravel application via Composer:

sudo composer create-project laravel/laravel /var/www/html/laravel && cd /var/www/html/laravel

Our new Laravel application is now ready to be served:

php artisan serve

To see our running Laravel application, visit http://127.0.0.1:8000 in a web browser in our local machine.

code . # Open your Laravel application in VS Code

Sometimes, you will need to work with databases, this is the "M" part in LEMP. To connect the Laravel application's database, update the .env environment configuration file:

DB_NAME=laravel
DB_USERNAME=root
DB_PASSWORD=

After your database connection has been set, start the migration script to create the database tables:

php artisan migrate

🎉🙌👏 Hurray! You now have a running Laravel application and confirms that you have successfully setup your LEMP:

In this chapter, we are simply serving our Laravel application using the built-in server php artisan serve. In the next Chapter, we will use Nginx to serve multiple Laravel applications without php artisan serve.

Install Mailpit

To install Mailpit

sudo bash < <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

After that, you should restart the shell just to make sure that the package has loaded properly. If you run:

mailpit

An output that looks like this should show:

Add uhe new domain to Windows C:\Windows\System32\drivers\etc\hosts file

127.0.0.1 mailpit

Congratulations, tada!! you’re all set. That’s it! you can now visit your frontend interface on:

http://mailpit:8025

Setting up your environment variables

You should copy and paste the env variables below in your .env file to instruct laravel mail facade on how to send the requisite mails

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=null

Forwarding our mails

You would notice though at this point that the mail host is localhost and for some reason , our smtp server is listening on the ip address 0.0.0.0. This just means that we have to instruct our smtp server to also listen on localhost because after_all, interacting with our localhost is as easy as it gets. To instruct our smtp server to listen on that port, We’d stop the current instance of our mailpit by pressing “CTRL + C” and then running our mailpit command again but this time with a few flags.

Make smtp server listen on localhost

mailpit --smtp  127.0.0.1:1025 --smtp-auth-allow-insecure --smtp-auth-accept-any

The —smtp flag is followed by [ip]:[port] and that instructs the server to listen on a certain port

The —smtp-auth-allow-insecure flag allows you to send mails without encryption

The —smtp-auth-accept-any flag allows you to send mails without a username and password

Your output should look like this:

At this point, you are officially done. You can run:

php artisan tinker

to enter the laravel command line and paste this command below to send your first mail:

\Mail::raw('Test email', function($message) {
    $message->to('[email protected]')
            ->subject('Test email');
});

You should see the notification immediately reflected on the frontend ui. Ensure that your mailpit and laravel backend are both running on your wsl.

Setup PHP with Mailpit

php --ini

We will see below output.

Configuration File (php.ini) Path: /etc/php/8.3/cli/etc
Loaded Configuration File:        /etc/php/8.3/cli/php.ini
Scan for additional .ini files in: (etc)
Additional .ini files parsed:      (etc)

Modify php.ini by following command.

sudo sed -i "s/;sendmail_path.*/sendmail_path='\/usr\/local\/bin\/mailpit sendmail [email protected]'/" /etc/php/8.3/cli/php.ini

Or we may modify php.ini manually, set sendmail_path to /usr/local/bin/mailpit sendmail [email protected]

sendmail_path='/usr/local/bin/mailpit sendmail [email protected]'

In case someone needs to apply the fix to several PHP versions you could use this script:

sudo vim fix_php_ini_mailpit.sh

Add the following content to the file:

#!/bin/bash

# Get the list of php.ini files
php_ini_files=$(find /etc/php/ -name php.ini)

# Loop through each php.ini file and apply the fix
for ini_file in $php_ini_files; do
    sudo sed -i "s|^;\?sendmail_path.*|sendmail_path = '/usr/local/bin/mailpit sendmail [email protected]'|" "$ini_file"

    # Check if the sed command was successful
    if [ $? -eq 0 ]; then
        echo "Fix applied to $ini_file"
    else
        echo "Error applying fix to $ini_file"
    fi
done

Save the file and make it executable:

sudo chmod +x fix_php_ini_mailpit.sh
./fix_php_ini_mailpit.sh #> To run the script

Restart PHP-FPM to apply the changes:

sudo service php8.3-fpm restart

Create Mailpit service

Now we are going make Mailpit service, So we don't have to start every time Mailpit after rebooting system.

open terminal and copy paste below content.

sudo tee /etc/systemd/system/mailpit.service <<EOL
[Unit]
Description=Mailpit - email testing for developers
[Service]
Type=simple
RemainAfterExit=no
ExecStart=/usr/local/bin/mailpit
[Install]
WantedBy=multi-user.target
EOL

To check status service is loaded successfully.

sudo systemctl status mailpit

Output should be like this.

mailpit.service - Mailpit
     Loaded: loaded (/etc/systemd/system/mailpit.service; disabled; vendor preset: enabled)
     Active: inactive (dead)

To start, stop or restart Mailpit, run:

sudo service mailpit start
sudo service mailpit stop
sudo service mailpit restart

Manage Multiple Laravel Applications and PHP Versions

Eventually, you will need to work with multiple Laravel applications, and perhaps even other PHP applications, each may require other PHP versions. This is managed by adding virtual host configurations for each Laravel application. Then, we add each domain to Windows C:\Windows\System32\drivers\etc\hosts file. This way, we will no longer need to run php artisan serve for each application every time, and, we will have more readable domains for each application, eg laravel.local, blog.test, todo.test, etc.

As an example, we will make our first Laravel application called "laravel" accessible at http://laravel.local. We will then create two additional Laravel applications called "todo" and "blog". Each application requires PHP 7.4 and PHP 8.2 and can be visited in a browser at http://todo.local and http://blog.local respectively. Of course, you may change the application names as needed.

Create the todo and blog Laravel applications in /var/www via Composer, then setup each application. Refer to Chapter Install PHP and Composer. Create a Laravel Application:

sudo composer create-project laravel/laravel /var/www/html/todo
sudo composer create-project laravel/laravel /var/www/html/blog

Next, give group ownership of our Laravel directory structures to the user and webserver group, and, change the permissions of the storage and bootstrap/cache directories to allow the web group write permissions. This is necessary for the application to function correctly:

sudo chown -R $USER:www-data /var/www/html/laravel/storage
sudo chown -R $USER:www-data /var/www/html/laravel/bootstrap/cache
sudo chmod -R 775 /var/www/html/laravel/storage
sudo chmod -R 775 /var/www/html/laravel/bootstrap/cache

sudo chown -R $USER:www-data /var/www/html/todo/storage
sudo chown -R $USER:www-data /var/www/html/todo/bootstrap/cache
sudo chmod -R 775 /var/www/html/todo/storage
sudo chmod -R 775 /var/www/html/todo/bootstrap/cache

sudo chown -R $USER:www-data /var/www/html/blog/storage
sudo chown -R $USER:www-data /var/www/html/blog/bootstrap/cache
sudo chmod -R 775 /var/www/html/blog/storage
sudo chmod -R 775 /var/www/html/blog/bootstrap/cache

Sometimes, you may need to clear temporary Laravel files before setting the permission:

php artisan route:clear
php artisan config:clear
php artisan cache:clear

Install Multiple PHP Versions

Note that Ubuntu 24.04 ships with PHP 8.3 by default. Officially, the only available version is PHP 8.3. To install alternative PHP versions, first, we need to add PHP repositories via Ondrej's Ubuntu Personal Package Archive (PPA):

sudo apt install lsb-release ca-certificates apt-transport-https software-properties-common
sudo add-apt-repository ppa:ondrej/php

We can now install multiple PHP versions and their respective recommended extensions for Laravel:

# Install PHP 5.6:
sudo apt install php5.6 php5.6-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 7.0:
sudo apt install php7.0 php7.0-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 7.1:
sudo apt install php7.1 php7.1-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 7.2:
sudo apt install php7.2 php7.2-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 7.3:
sudo apt install php7.3 php7.3-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 7.4:
sudo apt install php7.4 php7.4-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 8.0:
sudo apt install php8.0 php8.0-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 8.1:
sudo apt install php8.1 php8.1-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 8.2:
sudo apt install php8.2 php8.2-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

# Install PHP 8.3:
sudo apt install php8.3 php8.3-{common,cli,fpm,mysql,mbstring,xml,bcmath,zip,curl,gd,zip}

To change the PHP version used by the CLI, run:

sudo update-alternatives --set php /usr/bin/php5.6
sudo update-alternatives --set php /usr/bin/php7.0
sudo update-alternatives --set php /usr/bin/php7.1
sudo update-alternatives --set php /usr/bin/php7.2
sudo update-alternatives --set php /usr/bin/php7.3
sudo update-alternatives --set php /usr/bin/php7.4
sudo update-alternatives --set php /usr/bin/php8.0
sudo update-alternatives --set php /usr/bin/php8.1
sudo update-alternatives --set php /usr/bin/php8.2
sudo update-alternatives --set php /usr/bin/php8.3

To see and select the installed and active PHP versions interactively:

sudo update-alternatives --config php

Start, stop or restart the services each PHP versions:

# Start the services for each PHP version:
sudo service php5.6-fpm start
sudo service php7.0-fpm start
sudo service php7.1-fpm start
sudo service php7.2-fpm start
sudo service php7.3-fpm start
sudo service php7.4-fpm start
sudo service php8.0-fpm start
sudo service php8.1-fpm start
sudo service php8.2-fpm start
sudo service php8.3-fpm start

# Stop the services for each PHP version:
sudo service php5.6-fpm stop
sudo service php7.0-fpm stop
sudo service php7.1-fpm stop
sudo service php7.2-fpm stop
sudo service php7.3-fpm stop
sudo service php7.4-fpm stop
sudo service php8.0-fpm stop
sudo service php8.1-fpm stop
sudo service php8.2-fpm stop
sudo service php8.3-fpm stop

# Restart the services for each PHP version:
sudo service php5.6-fpm restart
sudo service php7.0-fpm restart
sudo service php7.1-fpm restart
sudo service php7.2-fpm restart
sudo service php7.3-fpm restart
sudo service php7.4-fpm restart
sudo service php8.0-fpm restart
sudo service php8.1-fpm restart
sudo service php8.2-fpm restart
sudo service php8.3-fpm restart

Go to your Nginx virtual hosts directory (/etc/nginx/sites-available) and create three virtual host configuration files for your laravel, todo and blog Laravel applications:

cd /etc/nginx/sites-available
sudo vim laravel.conf
sudo vim todo.conf
sudo vim blog.conf

Save the following recommended Nginx configuration for Laravel for each files, updating only the server_name, root and fastcgi_pass variables:

server {
    listen 80;

    # UPDATE BELOW: Use appropriate server_name for each Laravel application.
    server_name laravel.local;
    #server_name todo.local;
    #server_name blog.local;

    # UPDATE BELOW: Use appropriate root directory for each Laravel application.
    root /var/www/html/laravel/public;
    #root /var/www/html/todo/public;
    #root /var/www/html/blog/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    index index.html index.htm index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        # UPDATE BELOW: Use appropriate PHP version.
        # For example, to use PHP 7.4, replace php8.3-fpm to php7.4-fpm.
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        # The available PHP versions are php5.6, php7.0, php7.1, php7.2, php7.3, php7.4, php8.0, php8.1, php8.2 and php8.3.

        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

To activate the new virtual host configuration files, create symbolic links to laravel, todo and blog in sites-enabled:

sudo ln -s /etc/nginx/sites-available/laravel.conf /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/todo.conf /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/blog.conf /etc/nginx/sites-enabled/

Test Nginx for errors then restart:

sudo nginx -t
sudo service nginx restart

Add uhe three new domains to Windows C:\Windows\System32\drivers\etc\hosts file

127.0.0.1 laravel.local
127.0.0.1 todo.local
127.0.0.1 blog.local

In a browser, we can visit our new Laravel applications:

Virtualhost Manage Script by RoverWire

Bash Script to allow create or delete apache/nginx virtual hosts on Ubuntu on a quick way.

cd /usr/local/bin
wget -O virtualhost https://raw.githubusercontent.com/RoverWire/virtualhost/master/virtualhost-nginx.sh
chmod +x virtualhost

Usage

Basic command line syntax

sudo virtualhost [create | delete] [domain] [optional host_dir]
# For example
sudo virtualhost create laravel.local
sudo virtualhost create todo.local
sudo virtualhost create blog.local

Potential Nginx Errors and Fixes

To resolve the error File not found and HTTP Error 500 when accessing the site in the browser, and the error logged by Nginx at /var/log/nginx/error.log, stat() "/home/username/siteroot/public/" failed (13: Permission denied), make sure that Nginx has the proper permission to the project root directories:

chmod +x /home/
chmod +x /home/username
chmod +x /home/username/siteroot

Extras

Open a Laravel application source code in Visual Studio Code

Open an Ubuntu tab in Windows Terminal.

To open the current directory in Visual Studio Code, run:

code .

To open a specific file in Visual Studio Code, run:

code index.php

Open a Laravel application source code in Sublime Text 4

Sublime Text does not support opening directories inside WSL yet. To be able to do so, we need to do a little configuration.

First, add the following block of code below to your Bash configuration file (~/.bashrc, ~/.bash_profile or ~/.zshrc): alias subl='"/mnt/c/Program Files/Sublime Text/subl.exe"' Restart Windows Terminal after reloading your Bash script:

source ~/.bashrc

source ~/.bash_profile

source ~/.zshrc

Go to a Laravel application and open the project in Sublime Text 3/4.

cd ~/var/www/html/todo
subl .

To open a specific file, run:

subl index.php

Manage multiple LEMP services in one command

To create an easy-to-use command to manage our LEMP services in one command, add the following block of code below to your Bash configuration file (~/.bashrc, ~/.bash_profile or ~/.zshrc):

# Function to start|stop|restart LEMP services in one command.
# Example: $ sudo lemp start|stop|restart
lemp() {
    echo "

 __          _______ _
 \ \        / / ____| |
  \ \  /\  / / (___ | |
   \ \/  \/ / \___ \| |
    \  /\  /  ____) | |____
  _  \/  \/__|_____/|______|
 | |    |  ____|  \/  |  __ \
 | |    | |__  | \  / | |__) |
 | |    |  __| | |\/| |  ___/
 | |____| |____| |  | | |
 |______|______|_|  |_|_|


"
    echo "WSL LEMP: $1 Nginx, MySQL and PHP for Linux (LEMP)"
    sudo service nginx "$1"
    sudo service mysql "$1"
    sudo service php5.6-fpm "$1"
    sudo service php7.0-fpm "$1"
    sudo service php7.1-fpm "$1"
    sudo service php7.2-fpm "$1"
    sudo service php7.3-fpm "$1"
    sudo service php7.4-fpm "$1"
    sudo service php8.0-fpm "$1"
    sudo service php8.1-fpm "$1"
    sudo service php8.2-fpm "$1"
    sudo service php8.3-fpm "$1"
    echo "Done..."
}