From a2faf6d034f38f03d94c6cca8406eb469c5e6a9a Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Thu, 19 Jun 2025 14:55:38 +0300 Subject: [PATCH] Issue #78: Tweaked docs Signed-off-by: alexmerlin --- README.md | 4 +- docs/book/v1/faq.md | 2 +- docs/book/v1/introduction.md | 4 +- docs/book/v1/setup/installation.md | 18 ++++----- docs/book/v1/setup/setup-packages.md | 25 +++++++------ docs/book/v1/setup/system-requirements.md | 6 +-- .../v1/virtualhosts/create-virtualhost.md | 11 +++--- docs/book/v1/virtualhosts/overview.md | 6 +-- wsl/README.md | 37 ++++++++++--------- wsl/create-virtualhost.yml | 2 +- wsl/install.yml | 2 +- 11 files changed, 59 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index a7b31f0..ef107bf 100644 --- 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 index 604a9af..2815d05 100644 --- 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 index 6a3208f..e1768f9 100644 --- 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 index 57280cd..849e793 100644 --- 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 `, 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 ` after replacing `` 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. -[@ ]$ +[@ ]$ ``` diff --git a/docs/book/v1/setup/setup-packages.md b/docs/book/v1/setup/setup-packages.md index 766a06e..9f40530 100644 --- 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,7 +66,7 @@ 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: @@ -73,26 +74,26 @@ Once finished, check if everything works by opening in your browser: * [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 index 1191920..f4935e4 100644 --- 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 index 3c8e883..5104d1d 100644 --- 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 index 5326fb5..8d35d9c 100644 --- 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 index caaca4d..2f7e387 100644 --- 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 `, 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 ` after replacing `` 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. -[@ ]$ +[@ ]$ ``` -## 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,7 +194,7 @@ 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: @@ -201,9 +202,9 @@ Once finished, check if everything works by opening in your browser: * [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 index 882dbdd..7be6395 100644 --- 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 index 3e2d7f8..cc57c31 100644 --- 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