Merge pull request #80 from dotkernel/issue-78-2

alexmerlin · web-flow · commit b7d4b6accf3c · 2025-06-19T15:10:37.000+03:00
Issue 78: Tweaked docs
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ 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).
+If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux 9](wsl/README.md).
 
 ## Install WSL2
 
@@ -57,4 +57,4 @@ To test, run again the following command:
 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).
+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 AlmaLinux 9](wsl/README.md).
diff --git a/docs/book/v1/faq.md b/docs/book/v1/faq.md
@@ -1,4 +1,4 @@
-# Frequently asked questions
+# AlmaLinux 9 Frequently asked questions
 
 ## How do I switch to a different version of PHP?
 
diff --git a/docs/book/v1/introduction.md b/docs/book/v1/introduction.md
@@ -1,9 +1,9 @@
-# Introduction
+# AlmaLinux 9 Introduction
 
 `dotkernel/development` is a tool that helps you prepare your development environment with the following components:
 
 * **WSL2**: Windows Subsystem for Linux
-* **AlmaLinux9**: free and open source Linux distribution
+* **AlmaLinux 9**: free and open source Linux distribution
 * **PHP**: general-purpose scripting language geared towards web development
 * **Apache**: free and open-source cross-platform web server software
 * **MariaDB**: community-developed, commercially supported fork of the MySQL relational database management system
diff --git a/docs/book/v1/setup/installation.md b/docs/book/v1/setup/installation.md
@@ -1,4 +1,4 @@
-# Install AlmaLinux9
+# AlmaLinux 9 Installation
 
 Before proceeding with the installation, we need to make sure that no other WSL2 distribution (aka: _distro_) is running.
 This is important because this installation will fail if required ports are already in use by another distro.
@@ -19,21 +19,21 @@ If there is no other distro installed, you will see the below output (an empty l
   NAME            STATE           VERSION
 ```
 
-In this case, you can jump to the [installation](#install-almalinux9-1) section.
+In this case, you can jump to the [installation](#install-almalinux-9) section.
 
 If you have other distros installed, the output could look similar to the below:
 
 ```text
   NAME            STATE           VERSION
-* AlmaLinux-9     Stopped         2
+  AlmaLinux-9     Stopped         2
 * AlmaLinux-10    Running         2
 ```
 
 Make sure that the **STATE** column reads **Stopped** for all distros.
-If any of them reads **Running**, you must stop if first by executing `wsl -t <distro-name>`, for example: `wsl -t AlmaLinux-10`.
-Once you have stopped all distros, you can continue to the [installation](#install-almalinux9-1) section.
+If any of them reads **Running**, you must stop if first by executing `wsl -t <distro-name>` after replacing `<distro-name>` with the name of the distro you want to stop.
+Once you have stopped all distros, you can continue to the [installation](#install-almalinux-9) section.
 
-## Install AlmaLinux9
+## Install AlmaLinux 9
 
 List the available Linux distros by executing:
 
@@ -82,7 +82,7 @@ A distribution with the supplied name already exists. Use --name to choose a dif
 Error code: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS
 ```
 
-Install the AlmaLinux9 distro by executing the below command:
+Install the **AlmaLinux 9** distro by executing the below command:
 
 ```shell
 wsl --install -d AlmaLinux-9
@@ -101,7 +101,7 @@ 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`):
+This is the username you will use inside **AlmaLinux 9**, 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):
 
@@ -123,5 +123,5 @@ Finally, you should see the following message:
 
 ```text
 passwd: all authentication tokens updated successfully.
-[<your-almalinux9-username>@<your-device-name> <your-windows-username>]$
+[<your-alma-linux-9-username>@<your-device-name> <your-windows-username>]$
 ```
diff --git a/docs/book/v1/setup/setup-packages.md b/docs/book/v1/setup/setup-packages.md
@@ -1,4 +1,4 @@
-# Setup AlmaLinux9
+# AlmaLinux 9 Setup
 
 Install system packages:
 
@@ -9,7 +9,8 @@ sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/rem
 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:
+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.
@@ -18,7 +19,7 @@ We trust you have received the usual lecture from the local System Administrator
 [sudo] password for dotkernel:
 ```
 
-Input your AlmaLinux9 password and hit `Enter`.
+Input your **AlmaLinux 9** password and hit `Enter`.
 
 Update/Upgrade system packages:
 
@@ -32,7 +33,7 @@ Now, install the latest version of **Ansible**:
 sudo dnf install ansible -y
 ```
 
-Move inside your home directory (it is `/home/` followed by your AlmaLinux9 username, for example: `/home/dotkernel`):
+Move inside your home directory (it is `/home/` followed by your **AlmaLinux 9** username, for example: `/home/dotkernel`):
 
 ```shell
 cd ~
@@ -65,34 +66,34 @@ Install components by running the below Ansible command:
 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.
+The installation process will ask for your **AlmaLinux 9** 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.
+The installation is complete, your **AlmaLinux 9** 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**.
+> 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 **AlmaLinux 9**.
 
-## Running AlmaLinux9
+## Running AlmaLinux 9
 
 Open `Windows Terminal`.
 
-Start AlmaLinux9 by executing:
+Start **AlmaLinux 9** by executing:
 
 ```shell
-wsl -d AlmaLinux9
+wsl -d AlmaLinux-9
 ```
 
 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.
+This will open a new tab connected to **AlmaLinux 9**.
 
 ### Note
 
-> To run your applications using WSL2, you always need to be connected to your AlmaLinux9 distribution.
+> To run your applications using WSL2, you always need to be connected to your **AlmaLinux 9** distribution.
 > For this, all you need to do is to keep open an instance of Windows Terminal that is connected to it.
diff --git a/docs/book/v1/setup/system-requirements.md b/docs/book/v1/setup/system-requirements.md
@@ -1,4 +1,4 @@
-# System requirements
+# AlmaLinux 9 System requirements
 
 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...
@@ -23,7 +23,7 @@ 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](installation.md).
+If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux 9](installation.md).
 
 ## Install WSL2
 
@@ -55,4 +55,4 @@ To test, run again the following command:
 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](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 AlmaLinux 9](installation.md).
diff --git a/docs/book/v1/virtualhosts/create-virtualhost.md b/docs/book/v1/virtualhosts/create-virtualhost.md
@@ -1,4 +1,6 @@
-# Create virtualhosts
+# AlmaLinux 9 Create virtualhosts
+
+> By using the `*.localhost` pattern for any new virtualhost, you do not need to modify the `hosts` file in Windows, because these are routed by default.
 
 Move inside the directory `development/wsl`:
 
@@ -9,9 +11,7 @@ cd ~/development/wsl/
 If you don't already have a `config.yml` file, duplicate `config.yml.dist` as `config.yml`.
 
 Using your preferred text editor, open `config.yml` and, under the `virtualhosts` key, enter the virtualhosts that you want to create, each on its own line.
-
 Already existing virtualhosts will be skipped, their contents will not be lost, no need to comment or remove them.
-
 Save and close the file.
 
 Create the specified virtualhosts:
@@ -20,8 +20,7 @@ Create the specified virtualhosts:
 ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass
 ```
 
-This process will ask for your password (set during the installation process) and then iterate over the list of configured `virtualhosts` and will output a short summary with the results.
-
+This process will ask for your **AlmaLinux 9** password, iterate over the list of configured `virtualhosts` and output a short summary with the results.
 Your virtualhost should be accessible and ready to use.
 
 You will install your project under the `html` directory of your project, for example `/var/www/example.localhost/html`.
@@ -32,7 +31,7 @@ You will install your project under the `html` directory of your project, for ex
 
 ## Good to know
 
-* To run your installed projects, you need to start AlmaLinux9 first.
+* To run your installed projects, you need to start **AlmaLinux 9** 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](https://docs.dotkernel.org/development/v1/faq/#how-do-i-fix-common-permission-issues).
diff --git a/docs/book/v1/virtualhosts/overview.md b/docs/book/v1/virtualhosts/overview.md
@@ -1,4 +1,4 @@
-# Overview
+# AlmaLinux 9 Overview
 
 Virtualhosts allow developers to host multiple applications on their local system.
 
@@ -7,11 +7,11 @@ Using this tool, you configure a virtualhost for each of your applications, and
 **Example**:
 
 * `api.dotkernel.localhost`: this could be the endpoint where you host your website's API
-* `frontend.dotkernel.localhost`: this could be the subdomain you host your website's frontend that will consume the API
+* `frontend.dotkernel.localhost`: this could be the subdomain where you host your website's frontend that will consume the API
 
 In the above example, the URLs are built like this:
 
-* the subdomain is the identifier of your application (`api`/`frontend`)
+* the subdomain is the identifier of your application (`api` / `frontend`)
 * the domain is the identifier of your project (`dotkernel`)
 * the TLD sends the requests to localhost where Apache will route them to their real location
 
diff --git a/wsl/README.md b/wsl/README.md
@@ -1,4 +1,4 @@
-# Install AlmaLinux9
+# AlmaLinux 9 Installation
 
 Before proceeding with the installation, we need to make sure that no other WSL2 distribution (aka: _distro_) is running.
 This is important because this installation will fail if required ports are already in use by another distro.
@@ -19,21 +19,21 @@ If there is no other distro installed, you will see the below output (an empty l
   NAME            STATE           VERSION
 ```
 
-In this case, you can jump to the [installation](#install-almalinux9-1) section.
+In this case, you can jump to the [installation](#install-almalinux-9) section.
 
 If you have other distros installed, the output could look similar to the below:
 
 ```text
   NAME            STATE           VERSION
-* AlmaLinux-9     Stopped         2
+  AlmaLinux-9     Stopped         2
 * AlmaLinux-10    Running         2
 ```
 
 Make sure that the **STATE** column reads **Stopped** for all distros.
-If any of them reads **Running**, you must stop if first by executing `wsl -t <distro-name>`, for example: `wsl -t AlmaLinux-10`.
-Once you have stopped all distros, you can continue to the [installation](#install-almalinux9-1) section.
+If any of them reads **Running**, you must stop if first by executing `wsl -t <distro-name>` after replacing `<distro-name>` with the name of the distro you want to stop.
+Once you have stopped all distros, you can continue to the [installation](#install-almalinux-9) section.
 
-## Install AlmaLinux9
+## Install AlmaLinux 9
 
 List the available Linux distros by executing:
 
@@ -82,7 +82,7 @@ A distribution with the supplied name already exists. Use --name to choose a dif
 Error code: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS
 ```
 
-Install the AlmaLinux9 distro by executing the below command:
+Install the **AlmaLinux 9** distro by executing the below command:
 
 ```shell
 wsl --install -d AlmaLinux-9
@@ -101,7 +101,7 @@ 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`):
+This is the username you will use inside **AlmaLinux 9**, 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):
 
@@ -123,10 +123,10 @@ Finally, you should see the following message:
 
 ```text
 passwd: all authentication tokens updated successfully.
-[<your-almalinux9-username>@<your-device-name> <your-windows-username>]$
+[<your-alma-linux-9-username>@<your-device-name> <your-windows-username>]$
 ```
 
-## Setup AlmaLinux9
+## Setup AlmaLinux 9
 
 Install system packages:
 
@@ -137,7 +137,8 @@ sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/rem
 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:
+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.
@@ -146,7 +147,7 @@ We trust you have received the usual lecture from the local System Administrator
 [sudo] password for dotkernel:
 ```
 
-Input your AlmaLinux9 password and hit `Enter`.
+Input your **AlmaLinux 9** password and hit `Enter`.
 
 Update/Upgrade system packages:
 
@@ -160,7 +161,7 @@ Now, install the latest version of **Ansible**:
 sudo dnf install ansible -y
 ```
 
-Move inside your home directory (it is `/home/` followed by your AlmaLinux9 username, for example: `/home/dotkernel`):
+Move inside your home directory (it is `/home/` followed by your **AlmaLinux 9** username, for example: `/home/dotkernel`):
 
 ```shell
 cd ~
@@ -193,17 +194,17 @@ Install components by running the below Ansible command:
 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.
+The installation process will ask for your **AlmaLinux 9** 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.
+The installation is complete, your **AlmaLinux 9** 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**.
+> 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 **AlmaLinux 9**.
 
 ## Create virtualhosts
 
@@ -225,7 +226,7 @@ Create the specified virtualhosts:
 ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass
 ```
 
-This will iterate over the list of configured `virtualhosts` and will output a short summary with the results.
+This process will ask for your **AlmaLinux 9** password, iterate over the list of configured `virtualhosts` and output a short summary with the results.
 Your virtualhost should be accessible and ready to use.
 
 You will install your project under the `html` directory of your project, for example: `/var/www/example.localhost/html`.
@@ -236,7 +237,7 @@ You will install your project under the `html` directory of your project, for ex
 
 ### Good to know
 
-* To run your installed projects, you need to start AlmaLinux9 first.
+* To run your installed projects, you need to start **AlmaLinux 9** 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](https://docs.dotkernel.org/development/v1/faq/#how-do-i-fix-common-permission-issues).
diff --git a/wsl/create-virtualhost.yml b/wsl/create-virtualhost.yml
@@ -1,5 +1,5 @@
 ---
-- name: Create new virtualhost under AlmaLinux9
+- name: Create new virtualhost under AlmaLinux 9
   hosts: localhost
   connection: local
   become: true
diff --git a/wsl/install.yml b/wsl/install.yml
@@ -1,5 +1,5 @@
 ---
-- name: Setup AlmaLinux9 development environment
+- name: Setup AlmaLinux 9 development environment
   hosts: localhost
   connection: local
   become: true

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Frequently asked questions`
	`1`	`+# AlmaLinux 9 Frequently asked questions`
`2`	`2`
`3`	`3`	`## How do I switch to a different version of PHP?`
`4`	`4`