Merge pull request #59 from dotkernel/issue-58

Issue #58: Implement one distro per branch structure

Author: alexmerlin

README.md

@@ -1,13 +1,60 @@
-# Development environment
+# WSL2 development environment
 
-This is a collection of Ansible scripts allowing the creation and maintenance of your WSL2 development environment.
+This is a collection of Ansible scripts helping with the creation and maintenance of your WSL2 development environment.
 
-## Prerequisites
+If you're not already using it, we recommend you to install [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701?hl=en-US&gl=US).
+It is a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
 
-If you're not already using it, we recommend you to install [Windows Terminal](https://www.microsoft.com/en-US/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab).
+## Check if WLS2 is already available
 
-It's a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
+Open `Windows Terminal` and execute the following command:
 
-## Setup
+```shell
+wsl -v
+```
 
-Go to the [WSL2](wsl/README.md) setup page.
+The output should look similar to this:
+
+```text
+WSL version: 2.2.4.0
+Kernel version: 5.15.153.1-2
+WSLg version: 1.0.61
+MSRDC version: 1.2.5326
+Direct3D version: 1.611.1-81528511
+DXCore version: 10.0.26091.1-240325-1447.ge-release
+Windows version: 10.0.22631.3737
+```
+
+If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux9](wsl/README.md).
+
+## Install WSL2
+
+Before proceeding with the installation, please consult Microsoft's [documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites) regarding the minimum requirements for running WSL2.
+
+Once you identified that your machine can run WSL2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
+This will open a window where you can turn Windows features on/off.
+Make sure that the below features are activated (checked):
+
+* `Hyper-V` (including its sub-features)
+* `Virtual Machine Platform`
+* `Windows Subsystem for Linux`
+
+> If any of the above features are missing, then first you need to install them manually using [this guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual) and then continue with the below steps.
+
+Click `Ok` and restart your computer.
+
+Open Microsoft Store, search for `Windows Subsystem for Linux` and install it.
+
+Make sure that version **2** of WSL is set as default by executing the below command in Windows Terminal:
+
+```shell
+wsl --set-default-version 2
+```
+
+To test, run again the following command:
+
+```shell
+wsl -v
+```
+
+This time the output should display `WSL version: 2.x.x.x`, which means that your system is ready for using **WSL2** and you can proceed to [install AlmaLinux9](wsl/README.md).

docs/book/v1/faq.md renamed to docs/book/AlmaLinux9/faq.md

@@ -16,7 +16,7 @@ The aliases are the following:
 * `php81`: switch to PHP 8.1
 * `php82`: switch to PHP 8.2
 * `php83`: switch to PHP 8.3
-* `php83`: switch to PHP 8.4
+* `php84`: switch to PHP 8.4
 
 After switching to a different PHP version, test with the following command:
 

docs/book/v1/introduction.md renamed to docs/book/AlmaLinux9/introduction.md

@@ -0,0 +1,84 @@
+# Install AlmaLinux9
+
+Open `Windows Terminal`.
+
+List the available Linux distributions (aka: _distros_) by executing:
+
+```shell
+wsl --list --online
+```
+
+Depending on the list of distros available at the moment you run the command, the output should look similar to the below:
+
+```text
+The following is a list of valid distributions that can be installed.
+Install using 'wsl.exe --install <Distro>'.
+
+NAME                            FRIENDLY NAME
+AlmaLinux-8                     AlmaLinux OS 8
+AlmaLinux-9                     AlmaLinux OS 9
+AlmaLinux-Kitten-10             AlmaLinux OS Kitten 10
+AlmaLinux-10                    AlmaLinux OS 10
+Debian                          Debian GNU/Linux
+FedoraLinux-42                  Fedora Linux 42
+SUSE-Linux-Enterprise-15-SP5    SUSE Linux Enterprise 15 SP5
+SUSE-Linux-Enterprise-15-SP6    SUSE Linux Enterprise 15 SP6
+Ubuntu                          Ubuntu
+Ubuntu-24.04                    Ubuntu 24.04 LTS
+archlinux                       Arch Linux
+kali-linux                      Kali Linux Rolling
+openSUSE-Tumbleweed             openSUSE Tumbleweed
+openSUSE-Leap-15.6              openSUSE Leap 15.6
+Ubuntu-18.04                    Ubuntu 18.04 LTS
+Ubuntu-20.04                    Ubuntu 20.04 LTS
+Ubuntu-22.04                    Ubuntu 22.04 LTS
+OracleLinux_7_9                 Oracle Linux 7.9
+OracleLinux_8_7                 Oracle Linux 8.7
+OracleLinux_9_1                 Oracle Linux 9.1
+```
+
+Note the two columns: **NAME** and **FRIENDLY NAME**.
+To install a specific distro, use the value from the **NAME** column, in this case: `AlmaLinux-9`.
+Install the AlmaLinux9 distro by executing the below command:
+
+```shell
+wsl --install -d AlmaLinux-9
+```
+
+You should see the download progress - once finished, the output should look like this:
+
+```text
+Downloading: AlmaLinux OS 9
+Installing: AlmaLinux OS 9
+Distribution successfully installed. It can be launched via 'wsl.exe -d AlmaLinux-9'
+Launching AlmaLinux-9...
+Please create a default UNIX user account. The username does not need to match your Windows username.
+For more information visit: https://aka.ms/wslusers
+Enter new UNIX username:
+```
+
+As per the last line, the installation process now prompts you to enter a username.
+This is the username you will use inside AlmaLinux9, and it can be any alphanumeric string (for example `dotkernel`):
+
+Next, you are prompted to change the password associated with your chosen username (you will not see what you are typing, that's a security measure in Linux regarding passwords):
+
+```shell
+Enter new UNIX username: dotkernel.
+Changing password for user dotkernel.
+New password:
+```
+
+Depending on the strength of your password, you might get a `BAD PASSWORD: <some-reason>` message (if you want to choose a different password, hit `Enter` and you are taken back to previous step - else, continue with retyping your password):
+
+Next, you are asked to retype your password:
+
+```text
+Retype new password:
+```
+
+Finally, you should see the following message:
+
+```text
+passwd: all authentication tokens updated successfully.
+[<your-almalinux9-username>@<your-device-name> <your-windows-username>]$
+```

docs/book/AlmaLinux9/setup/installation.md

@@ -0,0 +1,98 @@
+# Setup AlmaLinux9
+
+Install system packages:
+
+```shell
+sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-9.rpm -y
+```
+
+You should see the below message, shown the first time you execute a command which requires elevated permissions (hence the `sudo` modifier at the beginning of the command).
+
+```text
+We trust you have received the usual lecture from the local System Administrator. It usually boils down to these three things:
+
+    #1) Respect the privacy of others.
+    #2) Think before you type.
+    #3) With great power comes great responsibility.
+
+[sudo] password for dotkernel:
+```
+
+Input your AlmaLinux9 password and hit `Enter`.
+
+Update/Upgrade system packages:
+
+```shell
+sudo dnf upgrade -y
+```
+
+Now, install the latest version of **Ansible**:
+
+```shell
+sudo dnf install ansible -y
+```
+
+Move inside your home directory (it is `/home/` followed by your AlmaLinux9 username, for example: `/home/dotkernel`):
+
+```shell
+cd ~
+```
+
+Clone the `almalinux9` branch of the `dotkernel/development` repository:
+
+```shell
+git clone --branch almalinux9 --single-branch https://github.com/dotkernel/development.git
+```
+
+Move inside the directory `development/wsl`:
+
+```shell
+cd development/wsl/
+```
+
+Duplicate `config.yml.dist` as `config.yml`:
+
+```shell
+cp config.yml.dist config.yml
+```
+
+Using your preferred text editor, open `config.yml` and fill in the empty fields.
+Save and close the file.
+
+Install components by running the below Ansible command:
+
+```shell
+ansible-playbook -i hosts install.yml --ask-become-pass
+```
+
+The installation process will ask for your AlmaLinux9 password, then iterate over each task in the playbook and output a short summary with the results.
+
+Once finished, check if everything works by opening in your browser:
+
+* [http://localhost/](http://localhost/): Apache's default home page
+* [http://localhost/info.php](http://localhost/info.php): PHP info page
+* [http://localhost/phpmyadmin/](http://localhost/phpmyadmin/): PhpMyAdmin (login with `root` + the root password you configured in `config.yml` under `mariadb` -> `root_password`)
+
+The installation is complete, your AlmaLinux9 development environment is ready to use.
+
+> Restart your `Windows Terminal` to find a new option in the tab selector, called **AlmaLinux-9** - clicking it will open a new tab connected to **AlmaLinux9**.
+
+## Running AlmaLinux9
+
+Open `Windows Terminal`.
+
+Start AlmaLinux9 by executing:
+
+```shell
+wsl -d AlmaLinux9
+```
+
+OR
+
+Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-9`.
+This will open a new tab connected to AlmaLinux9.
+
+### Note
+
+> To run your applications using WSL2, you always need to be connected to your AlmaLinux9 distribution.
+> For this, all you need to do is to keep open an instance of Windows Terminal that is connected to it.

docs/book/AlmaLinux9/setup/setup-packages.md

@@ -1,6 +1,11 @@
-# System Requirements
+# System requirements
 
-First, you need to check if your system is ready for using **WSL2**. Open `Windows Terminal` and execute the following command:
+If you're not already using it, we recommend you to install [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701?hl=en-US&gl=US).
+It is a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
+
+## Check if WLS2 is already available
+
+Open `Windows Terminal` and execute the following command:
 
 ```shell
 wsl -v
@@ -18,17 +23,15 @@ DXCore version: 10.0.26091.1-240325-1447.ge-release
 Windows version: 10.0.22631.3737
 ```
 
-If the output starts with `WSL version: 2.x`, you are ready to use **WSL2** and can continue with [the installation](installation.md).
+If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux9](installation.md).
 
-Else, you need to install **WSL2** and its components as shown below.
+## Install WSL2
 
-Before proceeding with the installation, please consult Microsoft's [documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites) regarding the minimum requirements for running **WSL2**.
-
-Once you know that your system can run **WSL2**, open the `Run` prompt by pressing `Win`+`r` and type in the dialog `OptionalFeatures`, then press `Enter`.
+Before proceeding with the installation, please consult Microsoft's [documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites) regarding the minimum requirements for running WSL2.
 
+Once you identified that your machine can run WSL2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
 This will open a window where you can turn Windows features on/off.
-
-Make sure the next features are activated (checked):
+Make sure that the below features are activated (checked):
 
 * `Hyper-V` (including its sub-features)
 * `Virtual Machine Platform`
@@ -40,7 +43,7 @@ Click `Ok` and restart your computer.
 
 Open Microsoft Store, search for `Windows Subsystem for Linux` and install it.
 
-Make sure **WSL2** is set as default by executing the below command in `Windows Terminal`:
+Make sure that version **2** of WSL is set as default by executing the below command in Windows Terminal:
 
 ```shell
 wsl --set-default-version 2
@@ -52,4 +55,4 @@ To test, run again the following command:
 wsl -v
 ```
 
-This time the output should display `WSL version: 2.x`, which means that your system is ready for using **WSL2** and you can continue with the [installation](installation.md).
+This time the output should display `WSL version: 2.x.x.x`, which means that your system is ready for using **WSL2** and you can proceed to [install AlmaLinux9](installation.md).

docs/book/v1/setup/system-requirements.md renamed to docs/book/AlmaLinux9/setup/system-requirements.md

@@ -35,6 +35,6 @@ You will install your project under the `html` directory of your project, for ex
 * To run your installed projects, you need to start AlmaLinux9 first.
 * If you work with virtualhosts, your projects are created under `/var/www/`.
 * You can still run PHP scripts under the default Apache project directory, located at `/var/www/html/`.
-* If you encounter write permission issues, see [this guide](../faq.md#how-do-i-fix-common-permission-issues).
-* This tool installs PHP 8.3 by default. If you need a different version, see [this guide](../faq.md#how-do-i-switch-to-a-different-version-of-php).
-* This tool installs Node.js 22 by default. If you need a different version, see [this guide](../faq.md#how-do-i-switch-to-a-different-version-of-nodejs).
+* If you encounter write permission issues, see [this guide](https://docs.dotkernel.org/development/almalinux9/faq/#how-do-i-fix-common-permission-issues).
+* We install PHP 8.3 by default - if you need a different version, see [this guide](https://docs.dotkernel.org/development/almalinux9/faq/#how-do-i-switch-to-a-different-version-of-php).
+* We install Node.js 22 by default - if you need a different version, see [this guide](https://docs.dotkernel.org/development/almalinux9/faq/#how-do-i-switch-to-a-different-version-of-nodejs).