Setting up Windows WSL for local Laravel development

Hi all! In this short article, I will very concisely tell you how to properly configure WSL on Windows 11 for local development of a Laravel application. We are going to install php, mysql, nginx and composer, and also edit the hosts file in Windows itself. In advance, I ask Docker fans not to be angry with me, here I am talking specifically about WSL.

So, without further delay, let's get started. And let's start with the fact that, as we assume, we have Windows and that's it. If WSL is already installed, you can skip the lion's part of the article.

Make sure your version of Windows is compatible with WSL.

Installing WSL

Open PowerShell as Administrator and write:

wsl.exe --install

Let's wait until all the components are installed, restart the computer, after which the WSL window will open automatically and Ubuntu will immediately start (Ubuntu will be installed by default), the system will ask you to specify the username and password for WSL.

PHP installation

We will install php 8.3. To do this, we write one by one:

sudo apt-get update
sudo apt install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt install openssl unzip php8.3-cli php8.3-bcmath php8.3-curl php8.3-mbstring php8.3-mysql php8.3-tokenizer php8.3-xml php8.3-zip php8.3-fpm

If no errors occur, then everything that needs to be installed is installed and we can continue.

Installing Composer

To install Composer we perform the following operations:

cd ~
curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
HASH=`curl -sS https://composer.github.io/installer.sig`
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

By running the command composer -v we should get something like this:

Installing MySQL

Now let's install the database:

sudo apt-get install mysql-server

After this we can change the user password to password or any other you like best. To do this we write:

sudo mysql
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

We write exit; and try to log into the database with a new password. Everything should work out.

mysql -u root -p

Installing Laravel

Next, we most likely follow a well-known path:

cd ~
mkdir dev
cd dev
composer create-project laravel/laravel test-app

Also, for Laravel to work, we need a database, so we create it:

mysql -uroot -p -e "create database test"

Be sure to edit in the Laravel application folder itself .env file something like this:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=test
DB_USERNAME=root
DB_PASSWORD=password

Now we install the tables necessary for Laravel into the database using artisan:

cd test-app
php artisan migrate

We should end up with something like this:

NGINX Installation and Configuration

The last thing we need to do is install the web server. To do this we write:

sudo apt-get install nginx

Now the important point: if we want to access our application at some specific address, then we must make some changes in the file C:\Windows\System32\drivers\etc\hosts. For example, we launch Notepad as Administrator and add the following entry at the end of the file:

127.0.0.1 test.test

Now let's create an nginx configuration file:

sudo nano /etc/nginx/sites-available/test.test.conf

In this file we write the following:

server {
    listen 80;
    listen [::]:80;
    server_name test.test;
    root /home/nikolay/dev/test-app/public;
 
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
 
    index 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$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
 
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Change directives server_name, root and, perhaps, fastcgi_pass, if you used other paths and names. After this we copy the created file to the directory sites-enabled nginx itself.

sudo ln -s /etc/nginx/sites-available/test.test.conf /etc/nginx/sites-enabled/test.test.conf

Checking the nginx configuration:

sudo nginx -t
sudo nginx -s reload

Another important point: in order for us not to have problems with rights, we must slightly change the configuration of nginx itself:

sudo nano /etc/nginx/nginx.conf

Here we change the very top line to match the WSL username (in my case, nikolay):

We also change the user group and the user himself in fpm:

sudo nano /etc/php/8.3/fpm/pool.d/www.conf

That's all! Now all that remains is to restart fpm and nginx:

sudo service php8.3-fpm restart
sudo service nginx restart

And now if we go through any browser to the address http://test.test we will see the main page of the freshly installed Laravel.

Thank you for your attention, I hope this little instruction will be useful.

PS Dear readers, the author in no way insists on such implementation of development for Windows. This article was written as a solution to a specific problem, and not as a recommendation for immediate action.