Merge pull request #65 from dotkernel/issue-54

Issue #54: Add AlmaLinux 10

Author: arhimede

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 AlmaLinux10](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 AlmaLinux10](wsl/README.md).

docs/book/v1/setup/installation.md

@@ -45,7 +45,7 @@ Install the AlmaLinux9 distro by executing the below command:
 wsl --install -d AlmaLinux-9
 ```
 
-You should see the download progress - once finished, the output should look like this:
+You should see the download progress—once finished, the output should look like this:
 
 ```text
 Downloading: AlmaLinux OS 9
@@ -68,7 +68,7 @@ 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):
+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 the previous step—else, continue with retyping your password):
 
 Next, you are asked to retype your password:
 

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

@@ -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.

docs/book/v1/virtualhosts/create-virtualhost.md

@@ -1,5 +1,7 @@
 # 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`:
 
 ```shell
@@ -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 AlmaLinux10 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`.

docs/book/v1/virtualhosts/overview.md

@@ -7,7 +7,7 @@ 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 domain you host your website's frontend that will consume the API
+* `frontend.dotkernel.localhost`: this could be subdomain where you host your website's frontend that will consume the API
 
 In the above example, the URLs are built like this:
 

docs/book/v2/faq.md

@@ -0,0 +1,198 @@
+# Frequently asked questions
+
+## How do I switch to a different version of PHP?
+
+Execute the following command:
+
+```shell
+sudo dnf module switch-to php:remi-{major}.{minor} -y
+```
+
+where `{major}.{minor}` is one of the supported PHP versions: `8.4`, `8.3`, `8.2` and `8.1`.
+
+Additionally, our setup includes predefined aliases for executing the above command.
+The aliases are the following:
+
+* `php81`: switch to PHP 8.1
+* `php82`: switch to PHP 8.2
+* `php83`: switch to PHP 8.3
+* `php84`: switch to PHP 8.4
+
+After switching to a different PHP version, test with the following command:
+
+```shell
+php -v
+```
+
+Depending on the selected PHP version, the output should look similar to the below:
+
+```text
+PHP 8.3.8 (cli) (built: Jun  4 2024 14:53:17) (NTS gcc x86_64)
+Copyright (c) The PHP Group
+Zend Engine v4.3.8, Copyright (c) Zend Technologies
+```
+
+## How do I switch to a different version of Node.js?
+
+Execute the following commands:
+
+```shell
+sudo dnf remove nodejs -y
+curl -fsSL https://rpm.nodesource.com/setup_{major}.x | sudo bash -
+sudo dnf install nodejs -y
+```
+
+where `{major}` is the Node.js version you want to switch to.
+
+Additionally, our setup includes predefined aliases for the above commands.
+The aliases are the following:
+
+* `node22`: switch to Node.js 22
+* `node20`: switch to Node.js 20
+* `node18`: switch to Node.js 18
+
+After switching to a different Node.js version, test with the following command:
+
+```shell
+node -v
+```
+
+## How do I fix common permission issues?
+
+If running your project, you encounter permission issues, follow the below steps.
+
+### Error
+
+> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data" is not writable...
+
+> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data/cache" is not writable...
+
+> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data/cache/doctrine" is not writable...
+
+### Solution
+
+```shell
+chmod -R 777 data
+```
+
+### Error
+
+> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/public/uploads" is not writable...
+
+### Solution
+
+```shell
+chmod -R 777 public/uploads
+```
+
+### Error
+
+> PHP Fatal error: Uncaught ErrorException: fopen(`<path-to-project>`/log/error-log-yyyy-mm-dd.log): Failed to open stream: Permission denied...
+
+### Solution
+
+```shell
+chmod -R 777 log
+```
+
+## Where are the error log files?
+
+From time to time, you are encountering various errors which are not displayed. Or you can get errors 500 in a browser.
+
+To find the error messages, you need to read the error log files.
+
+### Apache log files
+
+```text
+/var/log/httpd/error_log
+```
+
+### PHP-FPM log files
+
+```text
+/var/log/php-fpm/error.log
+/var/log/php-fpm/www-error.log
+```
+
+## How do I update Composer?
+
+Before updating, check your current Composer version by executing:
+
+```shell
+composer --version
+```
+
+The output should be similar to:
+
+```text
+Composer version 2.8.5 2025-01-21 15:23:40
+PHP version 8.3.20 (/usr/bin/php)
+Run the "diagnose" command to get more detailed diagnostics output.
+```
+
+Update Composer using its own `self-update` command:
+
+```shell
+sudo /usr/local/bin/composer self-update
+```
+
+The output should be similar to:
+
+```text
+Upgrading to version 2.8.8 (stable channel).
+
+Use composer self-update --rollback to return to version 2.8.5
+```
+
+After updating, check again your Composer version by executing:
+
+```shell
+composer --version
+```
+
+The output should be similar to:
+
+```text
+Composer version 2.8.8 2025-04-04 16:56:46
+PHP version 8.3.20 (/usr/bin/php)
+Run the "diagnose" command to get more detailed diagnostics output.
+```
+
+## How do I update phpMyAdmin?
+
+Being installed as a system package, it can be updated using the command which updates the rest of the system packages:
+
+```shell
+sudo dnf upgrade -y
+```
+
+## How do I create command aliases?
+
+From either your terminal or file explorer, navigate to your home directory (`/home/<your-username>/`).
+
+Using your preferred text editor, open the file: `.bash_profile` (if it does not exist, creat it first).
+
+Move to the end of the file and enter on a new line:
+
+```text
+alias command_alias="command to execute"
+```
+
+where:
+
+* `command_alias` is the name by which you want to call your original command
+* `command to execute`: the original command to be executed on alias call
+
+### Example
+
+```text
+alias list_files="ls -Al"
+```
+
+will create an alias called `list_files` that will run the command `ls -Al`.
+
+Then, you can execute your custom alias in a terminal just as a regular command:
+
+```shell
+list_files
+```

docs/book/v2/introduction.md

@@ -0,0 +1,13 @@
+# Introduction
+
+`dotkernel/development` is a tool that helps you prepare your development environment with the following components:
+
+* **WSL2**: Windows Subsystem for Linux
+* **AlmaLinux10**: 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
+* **Git**: distributed version control system
+* **Composer**: application-level dependency manager for the PHP
+* **Node.js**: JavaScript runtime environment
+* **PhpMyAdmin**: open source administration tool for MySQL and MariaDB

docs/book/v2/setup/installation.md

@@ -0,0 +1,83 @@
+# Install AlmaLinux10
+
+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-10`.
+Install the AlmaLinux10 distro by executing the below command:
+
+```shell
+wsl --install -d AlmaLinux-10
+```
+
+You should see the download progress—once finished, the output should look like this:
+
+```text
+Downloading: AlmaLinux OS 10
+Installing: AlmaLinux OS 10
+Distribution successfully installed. It can be launched via 'wsl.exe -d AlmaLinux-10'
+Launching AlmaLinux-10...
+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 AlmaLinux10, 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.
+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 the 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: password updated successfully
+[<your-almalinux10-username>@<your-device-name> <your-windows-username>]$
+```