PHP development environment with WSL 2 and Debian

Published on March 3rd, 2022
DALL-E: 16th century drawing of a web server

Please check WSL prerequisites before attempting this setup. This guide assumes that you have at least basic knowledge of linux operating systems.

In this setup we will be using Debian as our server distribution with Apache2/PHP-FPM as our web server. Also note that in this guide I sometimes reference Laravel framework, but this setup should work for most PHP projects. Let's get started with the first step.

Installing Debian

In your windows terminal enter the following.

wsl --install -d debian

This will download and install the latest version of Debian, in this case it's Debian 11 (Bullseye). Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution.

Next, access your distribution by typing wsl in your terminal of choice, or searching for Debian in your start menu. If you've done everything correctly now you should be inside your Debian terminal.

Next let's check for upgrades.

sudo apt update
sudo apt upgrade

Then we will need to install some default packages. I'm using vim as my preferred editor, you can change that as you wish.

sudo apt-get install lsb-release git openssl curl zsh vim wget

Install Apache 2 and PHP

We will be using Apache2 with PHP-FPM. Let's start by installing Apache package.

sudo apt-get install apt-transport-https ca-certificates apache2

Then we will enable some mods that we will be using.

sudo a2enmod headers
sudo a2enmod rewrite
sudo a2enmod ssl
sudo a2enmod remoteip

Next, add yourself to the www-data group.

sudo usermod -a -G www-data karlo

Now we will install and setup PHP. At the time of the writing, latest version of PHP is 8.1. First we need to add PHP package repository.

sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
sudo echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list
sudo apt-get update

Then we can install PHP and some default extensions.

sudo apt-get install php8.1 php8.1-pgsql php8.1-mbstring php8.1-xml php8.1-gd php8.1-imagick php8.1-curl php8.1-zip php8.1-xsl php8.1-soap php8.1-intl php8.1-bcmath

Then we will setup PHP-FPM.

sudo apt install php8.1-fpm libapache2-mod-fcgid
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.1-fpm

Now let's restart our services.

sudo service apache2 restart
sudo service php8.1-fpm restart

If you go to http://localhost you should see the default apache welcome page.

Apache 2 virtual hosts configuration

Next step is to configure our virtual hosts. Let's start by creating a self signed certificate for SSL access.

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/wsl.local.key -out /etc/ssl/certs/wsl.local.crt

This will generate our key and certificate file. Next let's create a new virtual host configuration.

sudo vim /etc/apache2/sites-available/website.local.conf

Here are the contents of the file. Note that this setup assumes you have a PHP project in /var/www/website directory. You can change your DocumentRoot and Directory variables to reflect your own settings. You can also use your windows folders, although I don't recommend it for performance reasons.

<VirtualHost *:443>
    ServerName website.local

    DocumentRoot /var/www/website/public/
    <Directory /var/www/website/public>
        AllowOverride all
        Require all granted
    </Directory>

    ErrorLog /var/log/apache2/website-error.log
    CustomLog /var/log/apache2/website-access.log combined

    SSLEngine On
    SSLCertificateFile      /etc/ssl/certs/wsl.local.crt
    SSLCertificateKeyFile   /etc/ssl/private/wsl.local.key
    SSLProtocol All -SSLv2 -SSLv3
</VirtualHost>

Now let's enable the site.

sudo a2ensite website.local
sudo service apache2 reload

Accessing the website

To access the website we need to modify our hosts file. You should be familiar with this process. Open your hosts file C:\Windows\System32\drivers\etc\hosts and add the following.

# WSL
::1	    website.local
127.0.0.1   website.local

Now if you visit https://website.local/ you should see your PHP project.

Installing database

For this example we will be installing PostgreSQL.

sudo apt install postgresql postgresql-contrib
sudo service postgresql start

To create a new database you can follow this example, first we open SQL console.

sudo -u postgres psql

Then in postgres console type the following commands.

--- Create user 'wsluser' with password 'secret'
CREATE ROLE wsluser LOGIN PASSWORD 'secret';
--- Create database with name laravel
CREATE DATABASE "laravel" WITH ENCODING='UTF8' OWNER=wsluser TEMPLATE template0;
--- Grant access
GRANT ALL PRIVILEGES ON DATABASE "laravel" to wsluser;

Setup XDebug

First we need to install XDebug extension.

sudo apt-get install php-xdebug

Then append the following to /etc/php/8.1/cli/conf.d/20-xdebug.ini file.

xdebug.mode = debug
xdebug.start_with_request = yes

Be sure to restart apache and php-fpm services after this setup.

Additional information

  • Main documentation for WSL is a great source for all your information.

  • You can access WSL files from Windows by visiting \\wsl$\Debian in explorer, or just type explorer.exe . inside WSL to open current folder in Windows.

  • To install and setup Node.js you need to follow this guide.

  • If you are using VSCode for development you should check out this extension.

  • Also you can open current folder in VSCode by typing code . inside WSL.

  • You will probably want to install composer, just follow command-line installation instructions.

  • If you have issues with folder permissions check out this post.

  • To shutdown WSL type wsl --shutdown inside your windows terminal.

  • Also every time your start WSL you need to start all your services manually. To make this easier I created start.sh file inside my home directory, and I run it every time with sudo ./start.sh.

#!/bin/sh
service apache2 start
service postgresql start
service php8.1-fpm start
service redis-server start

Find me on