From 360981953300fb88efb3f6ac437bdf125da1a37f Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Thu, 12 Jun 2025 12:57:58 +0300 Subject: [PATCH 1/2] Issue #54: Add AlmaLinux 10 Signed-off-by: alexmerlin --- README.md | 4 +- docs/book/v1/setup/installation.md | 4 +- docs/book/v1/setup/setup-packages.md | 3 +- .../v1/virtualhosts/create-virtualhost.md | 7 +- docs/book/v1/virtualhosts/overview.md | 2 +- docs/book/v2/faq.md | 198 ++++++++++++++++++ docs/book/v2/introduction.md | 13 ++ docs/book/v2/setup/installation.md | 83 ++++++++ docs/book/v2/setup/setup-packages.md | 104 +++++++++ docs/book/v2/setup/system-requirements.md | 58 +++++ .../v2/virtualhosts/create-virtualhost.md | 39 ++++ docs/book/v2/virtualhosts/overview.md | 18 ++ mkdocs.yml | 13 +- wsl/README.md | 61 +++--- wsl/create-virtualhost.yml | 2 +- wsl/install.yml | 2 +- wsl/roles/mariadb/tasks/main.yml | 8 +- wsl/roles/mariadb/templates/MariaDB.repo.j2 | 8 - wsl/roles/mariadb/vars/main.yml | 3 - wsl/roles/php/tasks/main.yml | 6 +- 20 files changed, 573 insertions(+), 63 deletions(-) create mode 100644 docs/book/v2/faq.md create mode 100644 docs/book/v2/introduction.md create mode 100644 docs/book/v2/setup/installation.md create mode 100644 docs/book/v2/setup/setup-packages.md create mode 100644 docs/book/v2/setup/system-requirements.md create mode 100644 docs/book/v2/virtualhosts/create-virtualhost.md create mode 100644 docs/book/v2/virtualhosts/overview.md delete mode 100644 wsl/roles/mariadb/templates/MariaDB.repo.j2 delete mode 100644 wsl/roles/mariadb/vars/main.yml diff --git a/README.md b/README.md index a7b31f0..4828795 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 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). diff --git a/docs/book/v1/setup/installation.md b/docs/book/v1/setup/installation.md index 08bdbc3..ca543a3 100644 --- a/docs/book/v1/setup/installation.md +++ b/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: ` 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: ` 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: diff --git a/docs/book/v1/setup/setup-packages.md b/docs/book/v1/setup/setup-packages.md index d1b2fd2..13afad1 100644 --- a/docs/book/v1/setup/setup-packages.md +++ b/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. diff --git a/docs/book/v1/virtualhosts/create-virtualhost.md b/docs/book/v1/virtualhosts/create-virtualhost.md index 3c8e883..6d1b809 100644 --- a/docs/book/v1/virtualhosts/create-virtualhost.md +++ b/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`. diff --git a/docs/book/v1/virtualhosts/overview.md b/docs/book/v1/virtualhosts/overview.md index 7dbb17e..36d7f10 100644 --- a/docs/book/v1/virtualhosts/overview.md +++ b/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: diff --git a/docs/book/v2/faq.md b/docs/book/v2/faq.md new file mode 100644 index 0000000..604a9af --- /dev/null +++ b/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 "``/data" is not writable... + +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache" is not writable... + +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache/doctrine" is not writable... + +### Solution + +```shell +chmod -R 777 data +``` + +### Error + +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not writable... + +### Solution + +```shell +chmod -R 777 public/uploads +``` + +### Error + +> PHP Fatal error: Uncaught ErrorException: fopen(``/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//`). + +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 +``` diff --git a/docs/book/v2/introduction.md b/docs/book/v2/introduction.md new file mode 100644 index 0000000..f0e1165 --- /dev/null +++ b/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 diff --git a/docs/book/v2/setup/installation.md b/docs/book/v2/setup/installation.md new file mode 100644 index 0000000..f47b321 --- /dev/null +++ b/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 '. + +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: ` 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 +[@ ]$ +``` diff --git a/docs/book/v2/setup/setup-packages.md b/docs/book/v2/setup/setup-packages.md new file mode 100644 index 0000000..6bc5710 --- /dev/null +++ b/docs/book/v2/setup/setup-packages.md @@ -0,0 +1,104 @@ +# Setup AlmaLinux10 + +Install system packages: + +```shell +# If install Ansible via pip: sudo dnf install epel-release dnf-utils python3-pip https://rpms.remirepo.net/enterprise/remi-release-10.rpm -y +sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-10.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. + +For security reasons, the password you type will not be visible. + +[sudo] password for dotkernel: +``` + +Input your AlmaLinux10 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 +# If install Ansible from packages: sudo dnf install ansible-core ansible-collection-community-general -y +# If install Ansible via pip: pip install ansible +``` + +Move inside your home directory (it is `/home/` followed by your AlmaLinux10 username, for example: `/home/dotkernel`): + +```shell +cd ~ +``` + +Clone the `alma-linux-10` branch of the `dotkernel/development` repository: + +```shell +git clone --branch alma-linux-10 --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 AlmaLinux10 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 AlmaLinux10 development environment is ready to use. + +> Restart your `Windows Terminal` to find a new option in the tab selector, called **AlmaLinux-10**; clicking it will open a new tab connected to **AlmaLinux10**. + +## Running AlmaLinux10 + +Open `Windows Terminal`. + +Start AlmaLinux10 by executing: + +```shell +wsl -d AlmaLinux10 +``` + +OR + +Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-10`. +This will open a new tab connected to AlmaLinux10. + +### Note + +> To run your applications using WSL2, you always need to be connected to your AlmaLinux10 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/v2/setup/system-requirements.md b/docs/book/v2/setup/system-requirements.md new file mode 100644 index 0000000..67b2b58 --- /dev/null +++ b/docs/book/v2/setup/system-requirements.md @@ -0,0 +1,58 @@ +# 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... + +## Check if WLS2 is already available + +Open `Windows Terminal` and execute the following command: + +```shell +wsl -v +``` + +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 AlmaLinux10](installation.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 AlmaLinux10](installation.md). diff --git a/docs/book/v2/virtualhosts/create-virtualhost.md b/docs/book/v2/virtualhosts/create-virtualhost.md new file mode 100644 index 0000000..4511ccd --- /dev/null +++ b/docs/book/v2/virtualhosts/create-virtualhost.md @@ -0,0 +1,39 @@ +# 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 +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: + +```shell +ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass +``` + +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`. + +> The virtualhost's document root is set to the `public` directory of the above location, for example `/var/www/example.localhost/html/public`. + +> If you want to have the DocumentRoot directly in `html` folder, you need to modify the file `/etc/httpd/sites-available/example.localhost`. + +## Good to know + +* To run your installed projects, you need to start AlmaLinux10 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/v2/faq/#how-do-i-fix-common-permission-issues). +* We install PHP 8.4 by default—if you need a different version, see [this guide](https://docs.dotkernel.org/development/v2/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/v2/faq/#how-do-i-switch-to-a-different-version-of-nodejs). diff --git a/docs/book/v2/virtualhosts/overview.md b/docs/book/v2/virtualhosts/overview.md new file mode 100644 index 0000000..36d7f10 --- /dev/null +++ b/docs/book/v2/virtualhosts/overview.md @@ -0,0 +1,18 @@ +# Overview + +Virtualhosts allow developers to host multiple applications on their local system. + +Using this tool, you configure a virtualhost for each of your applications, and it will create them so that you can start working with them. + +**Example**: + +* `api.dotkernel.localhost`: this could be the endpoint where you host your website's 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: + +* 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 + +> By using the pattern `*.localhost` for any new virtualhost, you do not need to modify the `hosts` file in Windows, because these are routed by default. diff --git a/mkdocs.yml b/mkdocs.yml index bbe7e20..62e12cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,11 +2,22 @@ docs_dir: docs/book site_dir: docs/html extra: project: Development - current_version: v1 + current_version: v2 versions: + - v2 - v1 nav: - Home: index.md + - v2: + - Introduction: v2/introduction.md + - Setup: + - System Requirements: v2/setup/system-requirements.md + - Installation: v2/setup/installation.md + - Setup Packages: v2/setup/setup-packages.md + - Virtualhosts: + - Overview: v2/virtualhosts/overview.md + - Create virtualhost: v2/virtualhosts/create-virtualhost.md + - FAQ: v2/faq.md - v1: - Introduction: v1/introduction.md - Setup: diff --git a/wsl/README.md b/wsl/README.md index ad3efe8..30b6788 100644 --- a/wsl/README.md +++ b/wsl/README.md @@ -1,4 +1,4 @@ -# Install AlmaLinux9 +# Install AlmaLinux10 Open `Windows Terminal`. @@ -38,37 +38,36 @@ 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: +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-9 +wsl --install -d AlmaLinux-10 ``` -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 -Installing: AlmaLinux OS 9 -Distribution successfully installed. It can be launched via 'wsl.exe -d AlmaLinux-9' -Launching AlmaLinux-9... +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 AlmaLinux9, and it can be any alphanumeric string (for example `dotkernel`): +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. -Changing password for user dotkernel. New password: ``` -Depending on the strength of your password, you might get a `BAD PASSWORD: ` 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: ` 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: @@ -80,15 +79,15 @@ Finally, you should see the following message: ```text passwd: all authentication tokens updated successfully. -[@ ]$ +[@ ]$ ``` -## Setup AlmaLinux9 +## Setup AlmaLinux10 Install system packages: ```shell -sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-9.rpm -y +sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-10.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). @@ -100,10 +99,12 @@ We trust you have received the usual lecture from the local System Administrator #2) Think before you type. #3) With great power comes great responsibility. +For security reasons, the password you type will not be visible. + [sudo] password for dotkernel: ``` -Input your AlmaLinux9 password and hit `Enter`. +Input your AlmaLinux10 password and hit `Enter`. Update/Upgrade system packages: @@ -117,16 +118,16 @@ 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 AlmaLinux10 username, for example: `/home/dotkernel`): ```shell cd ~ ``` -Clone the `almalinux9` branch of the `dotkernel/development` repository: +Clone the `alma-linux-10` branch of the `dotkernel/development` repository: ```shell -git clone --branch almalinux9 --single-branch https://github.com/dotkernel/development.git +git clone --branch alma-linux-10 --single-branch https://github.com/dotkernel/development.git ``` Move inside the directory `development/wsl`: @@ -150,7 +151,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 AlmaLinux10 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: @@ -158,9 +159,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 AlmaLinux10 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-10**; clicking it will open a new tab connected to **AlmaLinux10**. ## Create virtualhosts @@ -172,8 +173,10 @@ Move inside the directory `development/wsl`: 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 ones will be skipped, no need to comment or remove them. +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: @@ -182,10 +185,10 @@ 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 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`. +You will install your project under the `html` directory of your project, for example `/var/www/example.localhost/html`. > The virtualhost's document root is set to the `public` directory of the above location, for example `/var/www/example.localhost/html/public`. @@ -193,9 +196,9 @@ 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 AlmaLinux10 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). -* We install PHP 8.3 by default—if you need a different version, see [this guide](https://docs.dotkernel.org/development/v1/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/v1/faq/#how-do-i-switch-to-a-different-version-of-nodejs). +* If you encounter write permission issues, see [this guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues). +* We install PHP 8.4 by default—if you need a different version, see [this guide](https://docs.dotkernel.org/development/v2/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/v2/faq/#how-do-i-switch-to-a-different-version-of-nodejs). diff --git a/wsl/create-virtualhost.yml b/wsl/create-virtualhost.yml index 882dbdd..cb64693 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 AlmaLinux10 hosts: localhost connection: local become: true diff --git a/wsl/install.yml b/wsl/install.yml index 3e2d7f8..0509ddf 100644 --- a/wsl/install.yml +++ b/wsl/install.yml @@ -1,5 +1,5 @@ --- -- name: Setup AlmaLinux9 development environment +- name: Setup AlmaLinux10 development environment hosts: localhost connection: local become: true diff --git a/wsl/roles/mariadb/tasks/main.yml b/wsl/roles/mariadb/tasks/main.yml index 418cada..6adc9d9 100644 --- a/wsl/roles/mariadb/tasks/main.yml +++ b/wsl/roles/mariadb/tasks/main.yml @@ -1,12 +1,6 @@ --- -- name: Create MariaDB 11.4 repo file - template: - src: "{{ mariadb_repo_src }}" - dest: "{{ mariadb_repo_dest }}" - owner: "{{ config.system.username }}" - group: "{{ config.system.username }}" - name: Install MariaDB 11.4 - command: "dnf install python3-mysqlclient MariaDB-server MariaDB-client -y" + command: "dnf install mariadb-server -y" - name: Enable and start MariaDB service command: systemctl enable --now mariadb - name: Set MariaDB root password diff --git a/wsl/roles/mariadb/templates/MariaDB.repo.j2 b/wsl/roles/mariadb/templates/MariaDB.repo.j2 deleted file mode 100644 index 5fca53a..0000000 --- a/wsl/roles/mariadb/templates/MariaDB.repo.j2 +++ /dev/null @@ -1,8 +0,0 @@ -# MariaDB 11.4 RedHat repository list -# https://mariadb.org/download/ -[mariadb] -name = MariaDB -baseurl = https://ftp.bme.hu/pub/mirrors/mariadb/yum/11.4/rhel9-amd64 -gpgkey=https://ftp.bme.hu/pub/mirrors/mariadb/yum/RPM-GPG-KEY-MariaDB -enabled=1 -gpgcheck=0 diff --git a/wsl/roles/mariadb/vars/main.yml b/wsl/roles/mariadb/vars/main.yml deleted file mode 100644 index 4cafd8d..0000000 --- a/wsl/roles/mariadb/vars/main.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -mariadb_repo_src: MariaDB.repo.j2 -mariadb_repo_dest: /etc/yum.repos.d/MariaDB.repo diff --git a/wsl/roles/php/tasks/main.yml b/wsl/roles/php/tasks/main.yml index 53b6091..e216795 100644 --- a/wsl/roles/php/tasks/main.yml +++ b/wsl/roles/php/tasks/main.yml @@ -1,7 +1,7 @@ --- -- name: Install PHP 8.3 - command: dnf module install php:remi-8.3 -y -- name: Enable and start PHP 8.3 +- name: Install PHP 8.4 + command: dnf module install php:remi-8.4 -y +- name: Enable and start PHP 8.4 command: systemctl enable --now php-fpm - name: Create PHP info file template: From b171f7707a33e82a48bb4d93b0f0cfb98ff0dcec Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Thu, 12 Jun 2025 13:12:31 +0300 Subject: [PATCH 2/2] helper comments Signed-off-by: alexmerlin --- wsl/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/wsl/README.md b/wsl/README.md index 30b6788..a884c3d 100644 --- a/wsl/README.md +++ b/wsl/README.md @@ -87,6 +87,7 @@ passwd: all authentication tokens updated successfully. Install system packages: ```shell +# If install Ansible via pip: sudo dnf install epel-release dnf-utils python3-pip https://rpms.remirepo.net/enterprise/remi-release-10.rpm -y sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-10.rpm -y ``` @@ -116,6 +117,8 @@ Now, install the latest version of **Ansible**: ```shell sudo dnf install ansible -y +# If install Ansible from packages: sudo dnf install ansible-core ansible-collection-community-general -y +# If install Ansible via pip: pip install ansible ``` Move inside your home directory (it is `/home/` followed by your AlmaLinux10 username, for example: `/home/dotkernel`):