resonancedesigns/WSL-Local-Development-Environment-Setup-Guide.md

## WSL-Local-Development-Environment-Setup-Guide.md

      
    Raw
  

              WSL-Local-Development-Environment-Setup-Guide.md
            
          
    WSL Local Development Environment Setup Guide

Prerequisites

This guide assumes you have the following:

A computer with Hyper-V support enabled in your BIOS. Consult your motherboard manufactures documentation to verify that your motherboard supports Hyper-V and how to enable it.
At least 1GB of free space on your C: drive but realistically you'll need plenty more to do any actual work in WSL.
Windows 10 May 2020 (2004), Windows 10 May 2019 (1903), or Windows 10 November 2019 (1909).
Local admin permissions for your Windows user account
Virtual Machine Platform enabled in Windows features.

Install WSL and Linux Distribution

First we need to get WSL running in your Windows workstation.

Go to Windows start menu (windows key) and type in "features"
Select "Turn Windows features on or off"
In the list, check off the "Windows Subsystem for Linux" option and click the "OK" button
You should be prompted to restart your Windows machine, do so to complete the installation.
Once restarted, go the Windows start menu, look for "Microsoft Store" and run it
Search for Ubuntu in the Microsoft Store app
Select Ubuntu 22.04.2 LTS and install it
Once installed, run it and an Ubuntu console window will open and run the initial distribution installation.

The distribution installation will ask you to create a unique user and password.
Once the installation is finished close the Ubuntu terminal window.


Ubuntu OS Customization


To customize your terminal prompt, add the following to the end of your ~/.bashrc file in your users home directory in order to make the prompt display the current time, current user, and current folder without the full path:
export PS1='\[\033[0;35m\]\@ \[\033[0;33m\]\u \[\033[1m\]\033[3;34m\]\W\[\033[1;37m\] > \[\033[0;36m\]'

This can be customized to your liking. Look here for a full guide on terminal custumization:


Install LAMP Stack

After the distribution is installed you will be at a WSL terminal window as the new user you just created during the distribution installation. Go through the following steps to get the LAMP stack installed and configured.
Install Apache


Update package manager cache and install the apache2 package:
sudo apt update
sudo apt install apache2


Start the Apache service and verify that it is running:
sudo service apache2 start
sudo service apache2 status


If the output states * apache2 is running, verify that it is reachable by entering http://localhost into the address bar of any browser window. If you are greeted by the "Apache2 Ubuntu Default Page: It works" page, then you have completed the Apache installation successfully.


Install MySQL

Now that you have a web server up and running, you need to install the database system to be able to store and manage data for your site. MySQL is a popular database management system used within PHP environments.


Install the mysql-server package:
sudo apt install mysql-server


Normally at this point, we would run a security script that comes pre-installed with MySQL. However, as of July 2022, an error will occur when you run the mysql_secure_installation script without some further configuration. The reason is that this script will attempt to set a password for the installation’s root MySQL account but, by default on Ubuntu installations, this account is not configured to connect using a password. 


Prior to July 2022, this script would silently fail after attempting to set the root account password and continue on with the rest of the prompts. However, as of this writing the script will return the following error after you enter and confirm a password:
... Failed! Error: SET PASSWORD has no significance for user 'root'@'localhost' as the authentication method used doesn't store authentication data in the MySQL server. Please consider using ALTER USER instead if you want to change authentication parameters.

This will lead the script into a recursive loop which you can only get out of by closing your terminal window. 


Because the mysql_secure_installation script performs a number of other actions that are useful for keeping your MySQL installation secure, it’s still recommended that you run it before you begin using MySQL to manage your data. To avoid entering this recursive loop, though, you’ll need to first adjust how your root MySQL user authenticates.


Start the MySQL service:
sudo service mysql start


Open the MySQL CLI:
sudo mysql


Then run the following ALTER USER command to change the root user’s authentication method to one that uses a password. The following example changes the authentication method to mysql_native_password:
mysql> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';


After making this change, exit the MySQL CLI:
mysql> exit


Following that, you can run the mysql_secure_installation script without issue:
sudo mysql_secure_installation


The first prompt will ask if you want to configure the VALIDATE PASSWORD PLUGIN. Press any button other than Y to keep this disabled.


For the rest of the questions, press Y and hit the ENTER key at each prompt. This will remove some anonymous users and the test database, disable remote root logins, and load these new rules so that MySQL immediately respects the changes you have made.


When you’re finished, test whether you’re able to log in to the MySQL console by typing:
sudo mysql -p


If you are brought to the MySQL CLI after entering the MySQL root user password, the installation has completed successfully. Exit the MySQL CLI:
mysql> exit


MySQL Trouble-Shooting:


If you get this warning when starting the mysql service:
su: warning: cannot change directory to /nonexistent: No such file or directory

It means that the mysql user has not been assigned a home directory. This can cause issues with user and application access, and the mysql service in general.
To assign a home directory to the mysql user, execute the following commands:
sudo service mysql stop
sudo usermod -d /var/lib/mysql/ mysql
sudo service mysql start

If you didn't receive any warnings or errors, this likely fixed the issue. You can check to see that mysql is now running correctly by checking the service status:
sudo service mysql status

If it's running correctly you should see some output similar to the following:
Output
 * /usr/bin/mysqladmin  Ver 8.0.35-0ubuntu0.22.04.1 for Linux on x86_64 ((Ubuntu))
Copyright (c) 2000, 2023, Oracle and/or its affiliates.
	
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
	
Server version          8.0.35-0ubuntu0.22.04.1
Protocol version        10
Connection              Localhost via UNIX socket
UNIX socket             /var/run/mysqld/mysqld.sock
Uptime:                 17 sec
	
Threads: 2  Questions: 8  Slow queries: 0  Opens: 438  Flush tables: 3  Open tables: 27  Queries per second avg: 0.470


Install PHP

You have Apache installed to serve your content and MySQL installed to store and manage your data. PHP is the component of our setup that will process code to display dynamic content to the end-user. In addition to the php package, you’ll need php-mysql, a PHP module that allows PHP to communicate with MySQL-based databases. You’ll also need libapache2-mod-php to enable Apache to handle PHP files. Also included are several other PHP packages required by many popular PHP based applications such as WordPress and phpMyAdmin. Core PHP packages will automatically be installed as dependencies.


Install the PHP packages:
sudo apt install php libapache2-mod-php php-mysql php-gmp php-curl php-intl php-xmlrpc php-gd php-xml php-cli php-mbstring php-zip php-json


Once the installation is finished, run the following command to confirm your PHP version:
php -v

You should see some output similar to this:
Output
PHP 8.1.2-1ubuntu2.11 (cli) (built: Feb 22 2023 22:56:18) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
	with Zend OPcache v8.1.2-1ubuntu2.11, Copyright (c), by Zend Technologies


Post-Install

Now that the LAMP stack is installed, we need to go through some mandatory and some optional configuration steps in order to make the stack ready to develop in.
Apache Configuration

Change default Apache root document directory (Optional)
If you want to store the files that the Apache web server serves in a different location than the web root Apache comes configured with by default, you can run the following commands.


Change in apache2.conf default configuration file:
sudo sed -i "s;/var/www;/mnt/c/Dev/Projects/Web;g" /etc/apache2/apache2.conf


Change in 000-default.conf virtual host configuration file:
sudo sed -i "s;/var/www/html;/mnt/c/Dev/Projects/Web;g" /etc/apache2/sites-available/000-default.conf 


Add User To The www-data Group & Set File Permissions
We need to make sure that your user can add, modify, and execute files within Apache's web root.


Add your user to the www-data group with the $USER environment variable, which will reference your current system user:
sudo usermod -a -G www-data $USER


Assign 775 permissions the Apache web root:
sudo chmod 775 -R /var/www


Create Virtual Host
When using the Apache web server, you can create virtual hosts (similar to server blocks in Nginx) to encapsulate configuration details and host more than one domain from a single server. In this guide, we’ll set up a domain called < YOUR-DOMAIN >, but you should replace this with your own domain name.
Apache on Ubuntu 22.04 has one virtual host enabled by default that is configured to serve documents from the /var/www/html directory. While this works well for a single site, it can become unwieldy if you are hosting multiple sites. Instead of modifying /var/www/html, we’ll create a directory structure within /var/www for the < YOUR-DOMAIN > site, leaving /var/www/html in place as the default directory to be served if a client request doesn’t match any other sites.
Note
If you changed the default root in the previous optional step, you should define the locations in your host files configurations using that root directory.


Create the directory for < YOUR-DOMAIN > as follows:
sudo mkdir /var/www/< YOUR-DOMAIN >


If you changed your default Apache web root earlier, make the directory there instead:

sudo mkdir /mnt/c/Dev/Projects/Web/< YOUR-DOMAIN >


Copy the 000-default.conf virtual host configuration file to a new file in Apache’s sites-available directory:
sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/< YOUR-DOMAIN >.conf


Edit the new configuration file to work for your new project/site:
sudo nano /etc/apache2/sites-available/< YOUR-DOMAIN >.conf

You should edit the host file to look like something similar to the below:
<VirtualHost *:80>
	ServerAdmin info@resonance-designs.com
	ServerName < YOUR-DOMAIN >

	DocumentRoot /mnt/c/Dev/Projects/Web/LAMP/< YOUR-DOMAIN >

	<Directory /mnt/c/Dev/Projects/Web/LAMP/< YOUR-DOMAIN >>
		Options Indexes MultiViews
		AllowOverride All
		Require all granted
	</Directory>

	ErrorLog /mnt/c/Dev/Projects/Web/LAMP/< YOUR-DOMAIN >/logs/error.log
	CustomLog /mnt/c/Dev/Projects/Web/LAMP/< YOUR-DOMAIN >/logs/access.log combined
</VirtualHost>

Make sure the "logs" directory exists or Apache will fail to start/restart.


Enable the new host/site:
sudo a2ensite < YOUR-DOMAIN >.conf


Disable the default host/site:
sudo a2dissite 000-default.conf


Restart the Apache web server:
sudo service apache2 restart


Create index.html file to test the new host/site:
sudo nano /mnt/c/Dev/Projects/Web/LAMP/< YOUR-DOMAIN >/index.html

Put some content into the file similar to this:
<h1>Hello World!</h1>

Save the file then point your web browser to http://localhost and you should see the content you entered into the index.html file. Congrats, you successfully created a new site/host in your Apache web server.


Additional Server Software & Tools

phpMyAdmin (Optional)
The phpMyAdmin application allows easy access to the servers MySQL database through a web-based GUI


Install the phpMyAdmin package:


As your non-root sudo user, update your server’s package index if you haven’t done so recently:
sudo apt update


Run the following command to install the package onto your system. Please note, though, that the installation process requires you to make some choices to configure phpMyAdmin correctly. We’ll walk through these options shortly:
sudo apt install phpmyadmin

Here are the options you should choose when prompted in order to configure your installation correctly:


For the server selection, choose apache2

When the prompt appears, “apache2” is highlighted, but not selected. If you do not hit SPACE to select Apache, the installer will not move the necessary files during installation. Hit SPACE, TAB, and then ENTER to select Apache.


Select Yes when asked whether to use dbconfig-common to set up the database


You will then be asked to choose and confirm a MySQL application password for phpMyAdmin


If you followed this guide for installing MySQL, you may have decided to enable the Validate Password plugin. As of this writing, enabling this component will trigger an error when you attempt to set a password for the phpmyadmin user:

An error occured while installing the database:
mysql said: ERROR 1819 (HY000) at line 1: Your password does not satisfy the current policy requirements. 
Your options are:
<...>

To resolve this, select the abort option to stop the installation process. Then, open up your MySQL prompt:
sudo mysql

Or, if you enabled password authentication for the root MySQL user, run this command and then enter your password when prompted:
mysql -u root -p

From the prompt, run the following command to disable the Validate Password component. Note that this won’t actually uninstall it, but just stop the component from being loaded on your MySQL server:
UNINSTALL COMPONENT "file://component_validate_password";

Following that, you can close the MySQL client:
exit

Then try installing the phpmyadmin package again and it will work as expected:
sudo apt install phpmyadmin

Once phpMyAdmin is installed, you can open the MySQL prompt once again with sudo mysql or mysql -u root -p and then run the following command to re-enable the Validate Password component:
INSTALL COMPONENT "file://component_validate_password";

The installation process adds the phpMyAdmin Apache configuration file into the /etc/apache2/conf-enabled/ directory, where it is read automatically. To finish configuring Apache and PHP to work with phpMyAdmin, the only remaining task in this section of the tutorial is to is explicitly enable the mbstring PHP extension, which you can do by typing:
sudo phpenmod mbstring

Afterwards, restart Apache for your changes to be recognized:
sudo systemctl restart apache2

phpMyAdmin is now installed and configured to work with Apache. However, before you can log in and begin interacting with your MySQL databases, you will need to ensure that your MySQL users have the privileges required for interacting with the program.


Adjusting User Authentication and Privileges
When you installed phpMyAdmin onto your server, it automatically created a database user called phpmyadmin which performs certain underlying processes for the program. Rather than logging in as this user with the administrative password you set during installation, it’s recommended that you log in as either your root MySQL user or as a user dedicated to managing databases through the phpMyAdmin interface.


Configuring Password Access for the MySQL Root Account 

In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password. This allows for some greater security and usability in many cases, but it can also complicate things when you need to allow an external program — like phpMyAdmin — to access the user.
In order to log in to phpMyAdmin as your root MySQL user, you will need to switch its authentication method from auth_socket to one that makes use of a password, if you haven’t already done so. To do this, open up the MySQL prompt from your terminal:
sudo mysql

Next, check which authentication method each of your MySQL user accounts use with the following command:
SELECT user,authentication_string,plugin,host FROM mysql.user;

You should get some output similar to this:
+------------------+------------------------------------------------------------------------+-----------------------+-----------+
| user             | authentication_string                                                  | plugin                | host      |
+------------------+------------------------------------------------------------------------+-----------------------+-----------+
| debian-sys-maint | $A$005$I:jOry?]Sy<|qhQRj3fBRQ43i4UJxrpm.IaT6lOHkgveJjmeIjJrRe6         | caching_sha2_password | localhost |
| mysql.infoschema | $A$005$THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED | caching_sha2_password | localhost |
| mysql.session    | $A$005$THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED | caching_sha2_password | localhost |
| mysql.sys        | $A$005$THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED | caching_sha2_password | localhost |
| phpmyadmin       | $A$005$?#{Z?`gN!c2az)}V-INCWXSuVdqB9zWteH1IkZfTe/rOLgVhSzEMM9R3G6K9    | caching_sha2_password | localhost |
| root             |                                                                        | auth_socket           | localhost |
+------------------+------------------------------------------------------------------------+-----------------------+-----------+
6 rows in set (0.00 sec)

This example output indicates that the root user does in fact authenticate using the auth_socket plugin. To configure the root account to authenticate with a password, run the following ALTER USER command. Be sure to change password to a strong password of your choosing:
ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'password';


The previous ALTER USER statement sets the root MySQL user to authenticate with the caching_sha2_password plugin. Per the official MySQL documentation, caching_sha2_password is MySQL’s preferred authentication plugin, as it provides more secure password encryption than the older, but still widely used, mysql_native_password.
However, some versions of PHP don’t work reliably with caching_sha2_password. PHP has reported that this issue was fixed as of PHP 7.4, but if you encounter an error when trying to log in to phpMyAdmin later on, you may want to set root to authenticate with mysql_native_password instead:

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

Then, check the authentication methods employed by each of your users again to confirm that root no longer authenticates using the auth_socket plugin:
SELECT user,authentication_string,plugin,host FROM mysql.user;

You should get some output similar to this:
+------------------+------------------------------------------------------------------------+-----------------------+-----------+
| user             | authentication_string                                                  | plugin                | host      |
+------------------+------------------------------------------------------------------------+-----------------------+-----------+
| debian-sys-maint | $A$005$I:jOry?]Sy<|qhQRj3fBRQ43i4UJxrpm.IaT6lOHkgveJjmeIjJrRe6         | caching_sha2_password | localhost |
| mysql.infoschema | $A$005$THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED | caching_sha2_password | localhost |
| mysql.session    | $A$005$THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED | caching_sha2_password | localhost |
| mysql.sys        | $A$005$THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED | caching_sha2_password | localhost |
| phpmyadmin       | $A$005$?#{Z?`gN!c2az)}V-INCWXSuVdqB9zWteH1IkZfTe/rOLgVhSzEMM9R3G6K9    | caching_sha2_password | localhost |
| root             | $A$005$3y�y|Z?'_[} ZyVHuESVwNmjKWOH/ndETwS.Kty0IH7UfiXjOfVvyWroy4a.   | caching_sha2_password | localhost |
+------------------+------------------------------------------------------------------------+-----------------------+-----------+
6 rows in set (0.00 sec)

This output shows that the root user will authenticate using a password. You can now log in to the phpMyAdmin interface as your root user with the password you’ve set for it here.


Configuring Password Access for a Dedicated MySQL User 

Alternatively, some may find that it better suits their workflow to connect to phpMyAdmin with a dedicated user. To do this, open up the MySQL shell once again:
sudo mysql

If you have password authentication enabled for your root user, as described in the previous section, you will need to run the following command and enter your password when prompted in order to connect:
mysql -u root -p

From there, create a new user and give it a strong password:
CREATE USER '< YOUR-USER >'@'localhost' IDENTIFIED WITH caching_sha2_password BY '< YOUR-PASSWORD >';