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.
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
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
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.
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;
First we need to install XDebug extension.
sudo apt-get install php-xdebug
Then append the following to
xdebug.mode = debug xdebug.start_with_request = yes
Be sure to restart apache and php-fpm services after this setup.
Main documentation for WSL is a great source for all your information.
You can access WSL files from Windows by visiting
\\wsl$\Debianin 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 --shutdowninside your windows terminal.
Also every time your start WSL you need to start all your services manually. To make this easier I created
start.shfile inside my home directory, and I run it every time with
#!/bin/sh service apache2 start service postgresql start service php8.1-fpm start service redis-server start