WSL2 Local Dev Stack

Description

This is my local dev stack for the Windows Subsystem for Linux (WSL2). The stack consists of NGiNX, PHP7.4-fpm, and MariaDB. Additional tools and setup include: wp-cli, nvm (node version manager), SSL Certificates, and WindowsTerminal

Installation

WSL

First, you need to get WSL2 installed and activated. See here.

WindowsTerminal

Install Windows Terminal for easily managing your WSL install. It will integrate automatically, allowing you to work with bash in Ubuntu. See here for more info.

Ubuntu-20.04

Once you have WSL2 installed, you can open the Microsoft Store app and search for Ubuntu 20. Then, simply install it.

You should now have WSL installed with an Ubuntu-20.04 distro. Most of the commands referenced from this point on should be run in the Windows Terminal using Ubuntu.

Update Ubuntu

Make sure your distro is current:
sudo apt update && sudo apt upgrade -y

Install NGiNX

sudo apt install nginx

Then, start it:
sudo service nginx start

You should now be able to able open your browser and navigate to http://localhost/ and see the nginx welcome page.

On the Windows side of things you need to edit the hosts file. I suggest using PowerShell (Run as Administrator). The file is located at C:\Windows\System32\drivers\etc\hosts

At the bottom of the file add this line:

127.0.0.1      dev.local

Now, you should now be able to visit http://dev.local/ and see the page.

Configure NGiNX

I use vim for text editing in Ubuntu, but if you aren't comfy with it, just replace it with "nano" wherever you see "vim"

Set the default $EDITOR environment variable:
export EDITOR="/usr/bin/vim"

Now, let's create a config file:
sudoedit /etc/nginx/sites-available/dev.local

Add the following:

server {
        listen 80;
        server_name dev.local www.dev.local;

        # listen 443 ssl;
        # ssl_certificate;
        # ssl_certificate_key;

        root /var/www/dev.local;

        index index.php;

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

        location ~ \.php$ {
                include snippets/fastcgi-php.conf;
                fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        }

        location ~ /\.ht {
                deny all;
        }
}

TIP: Add more server blocks or config files for more sites.

Install PHP

Install php and other dependencies:
sudo apt install php-fpm php-common php-mysql php-gmp php-curl php-intl php-mbstring php-xmlrpc php-gd php-xml php-cli php-zip

Configure PHP

sudoedit /etc/php/7.4/fpm/php.ini

Change and uncomment if needed (short_open_tag is in 2 places):

short_open_tag = On
memory_limit = 256M
cgi.fix_pathinfo = 0
upload_max_filesize = 100M
max_execution_time = 360
date.timezone = America/Chicago

Stop php if it is running:
sudo service php7.4-fpm stop

Start php with new settings:
sudo service php7.4-fpm start

Install MariaDB

Install mariadb server; start it; and then run the initial installation script. Press enter when asked for existing password. Then set a new root password, and choose yes for the remaining questions.

sudo apt install mariadb-server

sudo service mysql start

sudo mysql_secure_installation

Create the superuser (this is only safe for local development). Replace user_name with your Ubuntu username and your_password with your Ubuntu password:

sudo mysql

CREATE USER 'user_name'@'localhost' IDENTIFIED BY 'your_password';

GRANT ALL PRIVILEGES ON * . * TO 'user_name'@'localhost';

FLUSH PRIVILEGES;

exit

Setup the web directory

cd /var/www/

sudo mkdir dev.local

Add yourself to the www-data group
sudo usermod -aG www-data $USER

Take ownership of the directory
sudo chown -R www-data:www-data dev.local

Change into the directory and let's add our first file:
cd dev.local

echo '<?php phpinfo(); ?>' >> index.php

Unlink the default NGiNX config:
sudo unlink /etc/nginx/sites-enabled/default

Add the new config we created earlier:
sudo ln -s /etc/nginx/sites-available/dev.local /etc/nginx/sites-enabled/dev.local

Check the new config for syntax errors:
sudo nginx -t

Reload and restart NGiNX:
sudo service nginx reload && sudo service nginx restart

If you refresh the page in your browser you should now see the php info output.

Create SSL Certificate

Generate the SSL Certificates using this command (replace dev.local with whatever url you've chosen to use). I create a folder ~/keys/ that I keep them in.

openssl req -x509 -out dev.local.crt -keyout dev.local.key -newkey rsa:2048 -nodes -sha256 -days 730 -subj '/CN=dev.local' -extensions EXT -config <(printf "[dn]\nCN=dev.local\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:dev.local\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Add the SSL certificate to Windows

First, copy the key somewhere easy to get to from explorer:
sudo cp ~/keys/dev.local.crt /mnt/c/Users/your_win_username/

Then, hit the windows key and type "Internet Options" and open the Internet Options application. Switch to the "Content" tab and then click on the "Certificates" button. In the Certificates window switch to the "Trusted Root Certificate Authorities" and click the "Import..." button. Follow the wizard, selecting the .crt file and complete the import. You should see the certificate in the list. Close the "Certificates" window and click the "Clear SSL State..." button on the "Internet Options" window. Click "Ok" to close Internet Options.

Add the SSL to NGiNX

Now, we need to go back to the nginx config in Ubuntu and uncomment the 3 lines for SSL and add the paths to the files.

sudoedit /etc/nginx/sites-available/dev.local

Uncomment the three lines for the SSL and configure like this:

listen 443 ssl;
ssl_certificate /home/your_username/keys/dev.local.crt;
ssl_certificate_key /home/your_username/keys/dev.local.key;

Restart NGiNX:
sudo service nginx reload && sudo service nginx restart

In your browser you should now be able to visit the https version. https://dev.local. If you have issues, you may need to reboot.

Install Tooling

NVM

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

nvm install 14

WP-CLI

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

php wp-cli.phar --info

chmod +x wp-cli.phar

sudo mv wp-cli.phar /usr/local/bin/wp

wp --info

Install WordPress

cd /var/www/dev.local

wp core download

Create the database using the mysql creds (same as my ubuntu creds because I want it to be easy)

mysql -uDB_Username -pDB_Userpass -e "CREATE DATABASE dev;"

wp config create --dbname=dev --dbuser=DB_Username --dbpass=DB_Userpass

The credentials in the following command will be your wordpress login.

wp core install --url=dev.local --title=Example --admin_user=supervisor --admin_password=strongpassword --admin_email=info@example.com

You should now have a working WordPress site with SSL!

Final Notes

To pull down a site from production, SSH into the remote and navigate to the wp-content folder. Run wp db export some_db_export.sql and logout of the remote. Remove everything in wp-content on the local. Then rsync the remote's wp-content to the local. Use WP-CLI to import the .sql file that was synced to wp-content. Swap out the production and local urls with the WP-CLI.
wp search-replace 'productiondomain.com' 'dev.local'
Add your WSL2 default username to /etc/sudoers, e.g., your_user_name ALL=(ALL) NOPASSWD: ALL on a single line and save the file. This will allow you to run sudo commands without a password. Reboot required.
Install Git on Windows and establish connection via ssh key. Make sure you can pull one of your private repos. Then, follow this to allow your WSL2 VM to use your hosts authentication. https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-git

nirvanadev/wsl2_local_dev_stack.md