From b69ab7acc9e1f8976f72ee5b9b83a03656f02264 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 24 Jul 2026 14:00:02 +0300 Subject: [PATCH 1/6] updated v2 folder --- docs/book/v2/setup/installation.md | 58 ++++++++++++++++++++++- docs/book/v2/setup/setup-packages.md | 52 +++++++++++++++++++- docs/book/v2/setup/system-requirements.md | 53 +++++++++++++++++---- 3 files changed, 151 insertions(+), 12 deletions(-) diff --git a/docs/book/v2/setup/installation.md b/docs/book/v2/setup/installation.md index 13e911e..c911b57 100644 --- a/docs/book/v2/setup/installation.md +++ b/docs/book/v2/setup/installation.md @@ -1,10 +1,20 @@ # Install AlmaLinux 10 on WSL 2 +## Summary + +Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. + > If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). +> This is step 2 of 3: [System Requirements](system-requirements.md) → **Install AlmaLinux 10** (this page) → [Setup Packages](setup-packages.md). + +> All commands on this page are executed in `Windows Terminal`, on your Windows host — not inside AlmaLinux 10. + Before proceeding with the installation, we need to make sure that no other WSL 2 distribution (aka: _distro_) is running. This is important because this installation will fail if required ports are already in use by another distro. +> The distro is downloaded over the internet, so make sure you have a stable connection. Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer. + Open `Windows Terminal`. ## Stop other WSL 2 distros @@ -32,7 +42,7 @@ If you have other distros installed, the output could look similar to the below: ``` 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 ` after replacing `` with the name of the distro you want to stop. +If any of them reads **Running**, you must stop it 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-10) section. ## Install AlmaLinux 10 @@ -126,3 +136,49 @@ Finally, you should see the following message: passwd: password updated successfully [@ ]$ ``` + +> At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). Keep this window open and continue directly with [Setup Packages](setup-packages.md) — its commands run inside AlmaLinux 10, not in Windows Terminal. If you close this window, see [Running on WSL 2](../running.md) to reconnect. + +## Next step + +Continue to [Setup Packages](setup-packages.md) to install the required system packages and provision your development environment. + +## FAQ + +### What if the installation fails because a distro is already running? + +Make sure no other WSL 2 distro is running by checking `wsl -l -v` — all distros must show **Stopped**. Stop any running distro with `wsl -t ` before retrying the installation. + +### What if `AlmaLinux-10` is already installed? + +The installation will fail with `A distribution with the supplied name already exists`. Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. + +### Does the username need to match my Windows username? + +No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. + +### What if I get a `BAD PASSWORD` message? + +This is just a strength warning. Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. + +### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? + +Run `wsl --list --online` to see the current list of installable distros and their **NAME** values. + +### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? + +This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled — revisit the [System Requirements](system-requirements.md) page and confirm both. A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. + +### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? + +You don't need the Store for this step — `wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. + +### How do I completely remove AlmaLinux-10 and start over? + +Unregister the distro, which deletes it and all its data, then reinstall it from scratch: + +```shell +wsl --unregister AlmaLinux-10 +``` + +Once unregistered, you can run `wsl --install -d AlmaLinux-10` again as described above. diff --git a/docs/book/v2/setup/setup-packages.md b/docs/book/v2/setup/setup-packages.md index 8542806..2772ad2 100644 --- a/docs/book/v2/setup/setup-packages.md +++ b/docs/book/v2/setup/setup-packages.md @@ -1,13 +1,23 @@ # AlmaLinux 10 Setup +## Summary + +Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. + > The instructions below also work without using WSL. +> This is step 3 of 3: [System Requirements](system-requirements.md) → [Install AlmaLinux 10](installation.md) → **Setup Packages** (this page). + +> All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. This is the same session left open at the end of the [installation](installation.md) step — if you closed it, see [Running on WSL 2](../running.md) to reconnect first. + Update/Upgrade system packages: ```shell sudo dnf upgrade -y ``` +> This step downloads packages over the internet and can take a few minutes depending on your connection speed and how many updates are pending. + 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 @@ -31,6 +41,8 @@ Install system packages: sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y ``` +> `$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. `dnf` verifies the package's GPG signature before installing it, same as any other package. + Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections: ```shell @@ -41,6 +53,8 @@ sudo dnf install ansible-core -y ansible-galaxy collection install community.general community.mysql ``` +> Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). If either command fails or times out, check your network connection first. + Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** username, for example: `/home/dotkernel`): ```shell @@ -65,7 +79,13 @@ Duplicate `config.yml.dist` as `config.yml`: cp config.yml.dist config.yml ``` -Using your preferred text editor, open `config.yml` and fill in the empty fields. +Using your preferred text editor, open `config.yml` and fill in the empty fields: + +* `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10. +* `config.mariadb.root_password`: the password to set for MariaDB's `root` user — you'll use this to log into phpMyAdmin later. +* `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed. +* `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is. + Save and close the file. Install components by running the below Ansible command: @@ -87,3 +107,33 @@ Once finished, check if everything works by opening in your browser: The installation is complete, your **AlmaLinux 10** development environment is ready to use. > If you are using WSL 2, 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 **AlmaLinux 10**. + +## Next step + +Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project. + +## FAQ + +### What if `config.yml` doesn't exist yet? + +Duplicate the provided template by running `cp config.yml.dist config.yml`, then fill in the empty fields before running the playbook. + +### What if the Ansible playbook fails partway through? + +Review the summary output for the failed task, fix the underlying issue (for example a misconfigured field in `config.yml`), and re-run `ansible-playbook -i hosts install.yml --ask-become-pass` — it is safe to re-run. + +### What if `ansible-galaxy collection install` fails or times out? + +This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. Check your connection and re-run the command — it's safe to run again even if some collections already installed successfully. + +### What if `http://localhost/` doesn't load after installation? + +If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. + +### How do I log into phpMyAdmin? + +Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. + +### Can I run this setup without WSL? + +Yes, the instructions work the same way on a non-WSL AlmaLinux system — just skip the WSL-specific notes. diff --git a/docs/book/v2/setup/system-requirements.md b/docs/book/v2/setup/system-requirements.md index e137459..a64a894 100644 --- a/docs/book/v2/setup/system-requirements.md +++ b/docs/book/v2/setup/system-requirements.md @@ -1,14 +1,36 @@ -# System requirements for AlmaLinux 10 on WSL 2 +# System Requirements for AlmaLinux 10 on WSL 2 + +## Summary + +Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. > If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). +> This is step 1 of 3 in setting up your development environment: **System Requirements** (this page) → [Install AlmaLinux 10](installation.md) → [Setup Packages](setup-packages.md). + +> All commands on this page are executed in `Windows Terminal`, on your Windows host — not inside AlmaLinux 10. + +## Minimum requirements + +Before installing WSL 2, make sure your machine meets the following: + +* Windows 10 version 1903 (build 18362) or higher, or Windows 11. +* A 64-bit processor with Second Level Address Translation (SLAT) support. +* Hardware virtualization enabled in your system's BIOS/UEFI (sometimes called `Intel VT-x`, `AMD-V`, or `SVM Mode`). +* At least 4 GB of RAM (8 GB or more recommended for running a full development stack comfortably). +* A few GB of free disk space for the distro plus additional space for your projects and databases. + +For the full, up-to-date list, see Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). + +## Check your WSL version + Open `Windows Terminal` and execute the following command: ```shell wsl -v ``` -The output should look similar to this: +The output should look similar to this (your version numbers will likely differ): ```text WSL version: 2.2.4.0 @@ -21,12 +43,11 @@ Windows version: 10.0.22631.3737 ``` If the output starts with `WSL version: 2.x.x.x`, you are ready to use WSL 2 and can proceed to [install AlmaLinux 10](installation.md). +If it doesn't (for example it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. ## Install WSL 2 -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 WSL 2. - -Once you identified that your machine can run WSL 2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`. +Once you've confirmed your machine meets the [minimum requirements](#minimum-requirements) above, 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): @@ -46,10 +67,22 @@ Make sure that version `2` of WSL is set as default by executing the below comma wsl --set-default-version 2 ``` -To test, run again the following command: +Run `wsl -v` again — this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). -```shell -wsl -v -``` +## FAQ + +### What if `wsl -v` shows WSL version 1 instead of 2? + +Run `wsl --set-default-version 2` and then re-run `wsl -v` to confirm the version has switched. + +### What if the `OptionalFeatures` dialog doesn't show all required features? + +Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. + +### Do I need to restart my computer after enabling the Windows features? + +Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. + +### What if my machine doesn't meet the minimum requirements for WSL 2? -This time the output should display `WSL version: 2.x.x.x`, which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). +Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI — this is the most common blocker. If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). From 56b391d2d7f73a58af384398c770de1148f2e316 Mon Sep 17 00:00:00 2001 From: bidi Date: Mon, 27 Jul 2026 13:18:32 +0300 Subject: [PATCH 2/6] updated v2 folder --- docs/book/v2/faq.md | 29 +++++++-- docs/book/v2/running.md | 59 +++++++++++++++++ docs/book/v2/setup/installation.md | 57 ++++++++++++---- docs/book/v2/setup/setup-packages.md | 43 ++++++++---- docs/book/v2/setup/system-requirements.md | 17 +++-- docs/book/v2/terminal.md | 14 +++- .../v2/virtualhosts/create-virtualhost.md | 65 ++++++++++++++++++- docs/book/v2/virtualhosts/overview.md | 35 +++++++++- 8 files changed, 277 insertions(+), 42 deletions(-) diff --git a/docs/book/v2/faq.md b/docs/book/v2/faq.md index 0c9436e..1fb208d 100644 --- a/docs/book/v2/faq.md +++ b/docs/book/v2/faq.md @@ -1,5 +1,17 @@ # AlmaLinux 10 Frequently asked questions +Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your development environment. + +* [How do I switch to a different version of PHP?](#how-do-i-switch-to-a-different-version-of-php) +* [How do I switch to a different version of Node.js?](#how-do-i-switch-to-a-different-version-of-nodejs) +* [How do I fix common permission issues?](#how-do-i-fix-common-permission-issues) +* [Where are the error log files?](#where-are-the-error-log-files) +* [How do I update Composer?](#how-do-i-update-composer) +* [How do I update phpMyAdmin?](#how-do-i-update-phpmyadmin) +* [How do I upgrade MariaDB?](#how-do-i-upgrade-mariadb) +* [How do I delete a virtualhost?](#how-do-i-delete-a-virtualhost) +* [How do I create command aliases?](#how-do-i-create-command-aliases) + ## How do I switch to a different version of PHP? Execute the following command: @@ -82,6 +94,9 @@ Depending on the current npm version, the output should look similar to the belo If running your project, you encounter permission issues, follow the below steps. +> `chmod -R 777` grants read/write/execute access to everyone, which is only appropriate for a local development environment like this one. +> Avoid carrying this habit into staging or production, where permissions should be scoped more narrowly (for example, to the web server's user/group). + ### Error > PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data" is not writable... @@ -160,7 +175,7 @@ sudo /usr/local/bin/composer self-update The output should be similar to: ```text -Upgrading to version 2.8.8 (stable channel). +Upgrading to version 2.9.0 (stable channel). Use composer self-update --rollback to return to version 2.8.5 ``` @@ -187,7 +202,7 @@ Being installed as a system package, it can be updated using the command which u sudo dnf upgrade -y ``` -## How do I upgrade MariaDB ? +## How do I upgrade MariaDB? Initially, MariaDB was at version 11.4 LTS. In case you want to upgrade to a different version, for instance [11.8 LTS](https://mariadb.org/11-8-is-lts/), use the below steps: @@ -239,7 +254,7 @@ sudo systemctl restart mariadb If for whatever reason you want to delete a virtualhost, for instance `to-be-deleted.localhost` you need to do the following: -* Delete the folder where are the files located +* Delete the folder where the files are located ```shell sudo rm -rf /var/www/to-be-deleted.localhost @@ -251,6 +266,12 @@ sudo rm -rf /var/www/to-be-deleted.localhost sudo rm -f /etc/httpd/sites-available/to-be-deleted.localhost.conf ``` +* Delete the enabled site symlink + +```shell +sudo rm -f /etc/httpd/sites-enabled/to-be-deleted.localhost.conf +``` + * Restart httpd server ```shell @@ -261,7 +282,7 @@ sudo systemctl restart httpd 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). +Using your preferred text editor, open the file: `.bash_profile` (if it does not exist, create it first). Move to the end of the file and enter on a new line: diff --git a/docs/book/v2/running.md b/docs/book/v2/running.md index 27c93c9..8d690ce 100644 --- a/docs/book/v2/running.md +++ b/docs/book/v2/running.md @@ -1,5 +1,9 @@ # Running AlmaLinux 10 on WSL 2 +## Summary + +Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. + > If you are not using WSL 2, connect via SSH with [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/). Open `Windows Terminal`. @@ -19,3 +23,58 @@ This will open a new tab connected to **AlmaLinux 10**. > For this, all you need to do is to launch it from a terminal, file explorer or an IDE. > Once launched, you can close the tool you launched it from. > It will stay connected until you shut it down manually or reboot your computer. + +## Check if AlmaLinux 10 is running + +From Windows Terminal, execute: + +```shell +wsl -l -v +``` + +Look for the `AlmaLinux-10` row — its **STATE** column reads **Running** if it's currently active, or **Stopped** otherwise. + +## Shut down AlmaLinux 10 + +To stop just the AlmaLinux 10 distro, leaving any other distros untouched: + +```shell +wsl -t AlmaLinux-10 +``` + +To shut down all currently running WSL 2 distros at once: + +```shell +wsl --shutdown +``` + +## Next step + +Continue to [Virtualhosts](virtualhosts/overview.md) to start hosting your projects. + +## FAQ + +### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? + +Confirm it's actually installed by running: + +```shell +wsl -l -v +``` + +If it's missing from the list entirely, revisit [Install AlmaLinux 10](setup/installation.md). +Restarting Windows Terminal after installation also helps it pick up the new tab profile. + +### What if `wsl -d AlmaLinux-10` fails to start? + +Run the below command to confirm the distro is installed and check its current state: + +```shell +wsl -l -v +``` + +If another distro is using the same resources, stop it first with the below command, then retry: + +```shell +wsl -t +``` diff --git a/docs/book/v2/setup/installation.md b/docs/book/v2/setup/installation.md index c911b57..b5fc7fc 100644 --- a/docs/book/v2/setup/installation.md +++ b/docs/book/v2/setup/installation.md @@ -8,12 +8,13 @@ Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl > This is step 2 of 3: [System Requirements](system-requirements.md) → **Install AlmaLinux 10** (this page) → [Setup Packages](setup-packages.md). -> All commands on this page are executed in `Windows Terminal`, on your Windows host — not inside AlmaLinux 10. +> All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. Before proceeding with the installation, we need to make sure that no other WSL 2 distribution (aka: _distro_) is running. This is important because this installation will fail if required ports are already in use by another distro. -> The distro is downloaded over the internet, so make sure you have a stable connection. Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer. +> The distro is downloaded over the internet, so make sure you have a stable connection. +> Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer. Open `Windows Terminal`. @@ -37,12 +38,17 @@ If you have other distros installed, the output could look similar to the below: ```text NAME STATE VERSION - AlmaLinux-8 Stopped 2 -* AlmaLinux-9 Running 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 it first by executing `wsl -t ` after replacing `` with the name of the distro you want to stop. +If any of them reads **Running**, you must stop it first by executing the below command, after replacing `` with the name of the distro you want to stop: + +```shell +wsl -t +``` + Once you have stopped all distros, you can continue to the [installation](#install-almalinux-10) section. ## Install AlmaLinux 10 @@ -100,7 +106,7 @@ Install the **AlmaLinux 10** distro by executing the below command: 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 10 @@ -122,7 +128,8 @@ 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): +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 or continue with retyping your password. Next, you are asked to retype your password: @@ -137,7 +144,10 @@ passwd: password updated successfully [@ ]$ ``` -> At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). Keep this window open and continue directly with [Setup Packages](setup-packages.md) — its commands run inside AlmaLinux 10, not in Windows Terminal. If you close this window, see [Running on WSL 2](../running.md) to reconnect. +> At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). +> Keep this window open and continue directly with [Setup Packages](setup-packages.md). +> Its commands run inside AlmaLinux 10, not in Windows Terminal. +> If you close this window, see [Running on WSL 2](../running.md) to reconnect. ## Next step @@ -147,11 +157,22 @@ Continue to [Setup Packages](setup-packages.md) to install the required system p ### What if the installation fails because a distro is already running? -Make sure no other WSL 2 distro is running by checking `wsl -l -v` — all distros must show **Stopped**. Stop any running distro with `wsl -t ` before retrying the installation. +Make sure no other WSL 2 distro is running by checking: + +```shell +wsl -l -v +``` + +All distros must show **Stopped**. Stop any running distro with the below command before retrying the installation: + +```shell +wsl -t +``` ### What if `AlmaLinux-10` is already installed? -The installation will fail with `A distribution with the supplied name already exists`. Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. +The installation will fail with `A distribution with the supplied name already exists`. +Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. ### Does the username need to match my Windows username? @@ -159,19 +180,27 @@ No, the Unix username created during installation can be any alphanumeric string ### What if I get a `BAD PASSWORD` message? -This is just a strength warning. Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. +This is just a strength warning. +Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. ### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? -Run `wsl --list --online` to see the current list of installable distros and their **NAME** values. +Run the below command to see the current list of installable distros and their **NAME** values: + +```shell +wsl --list --online +``` ### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? -This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled — revisit the [System Requirements](system-requirements.md) page and confirm both. A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. +This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. +Revisit the [System Requirements](system-requirements.md) page and confirm both. +A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. ### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? -You don't need the Store for this step — `wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. +You don't need the Store for this step. +`wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. ### How do I completely remove AlmaLinux-10 and start over? diff --git a/docs/book/v2/setup/setup-packages.md b/docs/book/v2/setup/setup-packages.md index 2772ad2..21ef27b 100644 --- a/docs/book/v2/setup/setup-packages.md +++ b/docs/book/v2/setup/setup-packages.md @@ -8,7 +8,9 @@ Update system packages, install Ansible and required repositories, clone this re > This is step 3 of 3: [System Requirements](system-requirements.md) → [Install AlmaLinux 10](installation.md) → **Setup Packages** (this page). -> All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. This is the same session left open at the end of the [installation](installation.md) step — if you closed it, see [Running on WSL 2](../running.md) to reconnect first. +> All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. +> This is the same session left open at the end of the [installation](installation.md) step. +> If you closed it, see [Running on WSL 2](../running.md) to reconnect first. Update/Upgrade system packages: @@ -41,7 +43,8 @@ Install system packages: sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y ``` -> `$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. `dnf` verifies the package's GPG signature before installing it, same as any other package. +> `$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. +> `dnf` verifies the package's GPG signature before installing it, same as any other package. Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections: @@ -53,7 +56,8 @@ sudo dnf install ansible-core -y ansible-galaxy collection install community.general community.mysql ``` -> Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). If either command fails or times out, check your network connection first. +> Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). +> If either command fails or times out, check your network connection first. Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** username, for example: `/home/dotkernel`): @@ -82,7 +86,7 @@ cp config.yml.dist config.yml Using your preferred text editor, open `config.yml` and fill in the empty fields: * `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10. -* `config.mariadb.root_password`: the password to set for MariaDB's `root` user — you'll use this to log into phpMyAdmin later. +* `config.mariadb.root_password`: the password to set for MariaDB's `root` user (you'll use this to log into phpMyAdmin later). * `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed. * `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is. @@ -94,7 +98,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 **AlmaLinux 10** 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 10** 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: @@ -106,7 +110,8 @@ Once finished, check if everything works by opening in your browser: The installation is complete, your **AlmaLinux 10** development environment is ready to use. -> If you are using WSL 2, 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 **AlmaLinux 10**. +> If you are using WSL 2, 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 **AlmaLinux 10**. ## Next step @@ -116,19 +121,34 @@ Your environment is now provisioned. Continue to [Running on WSL 2](../running.m ### What if `config.yml` doesn't exist yet? -Duplicate the provided template by running `cp config.yml.dist config.yml`, then fill in the empty fields before running the playbook. +Duplicate the provided template by running: + +```shell +cp config.yml.dist config.yml +``` + +Then fill in the empty fields before running the playbook. ### What if the Ansible playbook fails partway through? -Review the summary output for the failed task, fix the underlying issue (for example a misconfigured field in `config.yml`), and re-run `ansible-playbook -i hosts install.yml --ask-become-pass` — it is safe to re-run. +Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: + +```shell +ansible-playbook -i hosts install.yml --ask-become-pass +``` + +It is safe to re-run. ### What if `ansible-galaxy collection install` fails or times out? -This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. Check your connection and re-run the command — it's safe to run again even if some collections already installed successfully. +This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. +Check your connection and re-run the command. +It's safe to run again even if some collections already installed successfully. ### What if `http://localhost/` doesn't load after installation? -If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. +If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. +Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. ### How do I log into phpMyAdmin? @@ -136,4 +156,5 @@ Use the username `root` and the password you configured under `mariadb` -> `root ### Can I run this setup without WSL? -Yes, the instructions work the same way on a non-WSL AlmaLinux system — just skip the WSL-specific notes. +Yes, the instructions work the same way on a non-WSL AlmaLinux system. +You can then skip the WSL-specific notes. diff --git a/docs/book/v2/setup/system-requirements.md b/docs/book/v2/setup/system-requirements.md index a64a894..3a6fa03 100644 --- a/docs/book/v2/setup/system-requirements.md +++ b/docs/book/v2/setup/system-requirements.md @@ -8,7 +8,7 @@ Check whether WSL 2 is already installed and, if not, enable the required Window > This is step 1 of 3 in setting up your development environment: **System Requirements** (this page) → [Install AlmaLinux 10](installation.md) → [Setup Packages](setup-packages.md). -> All commands on this page are executed in `Windows Terminal`, on your Windows host — not inside AlmaLinux 10. +> All commands on this page are executed in `Windows Terminal`, on your Windows host - not inside AlmaLinux 10. ## Minimum requirements @@ -43,7 +43,7 @@ Windows version: 10.0.22631.3737 ``` If the output starts with `WSL version: 2.x.x.x`, you are ready to use WSL 2 and can proceed to [install AlmaLinux 10](installation.md). -If it doesn't (for example it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. +If it doesn't (for example, it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. ## Install WSL 2 @@ -67,13 +67,19 @@ Make sure that version `2` of WSL is set as default by executing the below comma wsl --set-default-version 2 ``` -Run `wsl -v` again — this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). +Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). ## FAQ ### What if `wsl -v` shows WSL version 1 instead of 2? -Run `wsl --set-default-version 2` and then re-run `wsl -v` to confirm the version has switched. +Run: + +```shell +wsl --set-default-version 2 +``` + +Then re-run `wsl -v` to confirm the version has switched. ### What if the `OptionalFeatures` dialog doesn't show all required features? @@ -85,4 +91,5 @@ Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog ### What if my machine doesn't meet the minimum requirements for WSL 2? -Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI — this is the most common blocker. If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). +Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. +If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). diff --git a/docs/book/v2/terminal.md b/docs/book/v2/terminal.md index 31ad62b..86652a7 100644 --- a/docs/book/v2/terminal.md +++ b/docs/book/v2/terminal.md @@ -1,6 +1,16 @@ # Terminal +## Summary + +Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. + > If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). -If you're not already using it, we recommend you to install [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701?hl=en-US&gl=US). -It is a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more... +If you're not already using it, we recommend installing [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. + +Once your AlmaLinux 10 distro is installed, it gets its own dedicated tab profile in Windows Terminal (see [Running on WSL 2](running.md)), so every command in this guide (Windows and Linux alike) can be run from the same app. + +## Next step + +Continue to [System Requirements](setup/system-requirements.md) to check whether your machine is ready for WSL 2. diff --git a/docs/book/v2/virtualhosts/create-virtualhost.md b/docs/book/v2/virtualhosts/create-virtualhost.md index a10daea..7f00ef2 100644 --- a/docs/book/v2/virtualhosts/create-virtualhost.md +++ b/docs/book/v2/virtualhosts/create-virtualhost.md @@ -1,7 +1,14 @@ # AlmaLinux 10 Create virtualhosts +## Summary + +Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. + > 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. +> This assumes you've already completed [Setup Packages](../setup/setup-packages.md). +> Apache must already be installed before virtualhosts can be created. + Move inside the directory `development/wsl`: ```shell @@ -12,6 +19,13 @@ If you don't already have a `config.yml` file, duplicate `config.yml.dist` as `c 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. + +> Virtualhost names should be valid hostnames (lowercase letters, numbers, and hyphens) ending in `.localhost`, for example `api.dotkernel.localhost`. +> Avoid spaces or other special characters. + +> You can come back and add more virtualhosts at any time: add new lines under `virtualhosts` and re-run the playbook. +> Existing virtualhosts are left untouched. + Save and close the file. Create the specified virtualhosts: @@ -20,7 +34,7 @@ Create the specified virtualhosts: ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass ``` -This process will ask for your **AlmaLinux 10** password, iterate over the list of configured `virtualhosts` and output a short summary with the results. +This process will ask for your **AlmaLinux 10** password, iterate over the list of configured, 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`. @@ -29,11 +43,56 @@ You will install your project under the `html` directory of your project, for ex > If you want to have the DocumentRoot directly in `html` folder, you need to modify the file `/etc/httpd/sites-available/example.localhost`. +> A freshly created virtualhost only has an empty `html` directory - `html/public` doesn't exist yet. +> Visiting the virtualhost's URL in your browser will show an error until you place a project there, this is expected. + +> Apache logs for each virtualhost are stored separately, for example `/var/www/example.localhost/log/error.log` and `/var/www/example.localhost/log/requests.log`. +> Check these first if something isn't working as expected. + ## Good to know * To run your installed projects, you need to start **AlmaLinux 10** 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). +* 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). + +## FAQ + +### What if I don't have a `config.yml` file yet? + +Duplicate the provided template by running the below command inside `development/wsl`: + +```shell +cp config.yml.dist config.yml +``` + +Then add your virtualhosts under the `virtualhosts` key. + +### What happens if I list a virtualhost that already exists? + +It will simply be skipped. +Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from `config.yml`. + +### Where should I put my project's files? + +Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. +The document root is set to the `public` subdirectory of that location, for example `/var/www/example.localhost/html/public`. + +### How do I make the DocumentRoot point directly to `html` instead of `html/public`? + +Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. + +### How do I access my virtualhost if AlmaLinux 10 isn't running? + +You need to start **AlmaLinux 10** first. +Your virtualhosts are only reachable while the distro is running. + +### What if I hit permission errors when writing to my project's files? + +See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. + +### How do I delete a virtualhost I no longer need? + +See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. diff --git a/docs/book/v2/virtualhosts/overview.md b/docs/book/v2/virtualhosts/overview.md index 629ebf9..1e7f3a4 100644 --- a/docs/book/v2/virtualhosts/overview.md +++ b/docs/book/v2/virtualhosts/overview.md @@ -1,5 +1,9 @@ # AlmaLinux 10 Overview +## Summary + +Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. + 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. @@ -11,8 +15,33 @@ Using this tool, you configure a virtualhost for each of your applications, and 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 +* 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. + +## Next step + +Ready to set one up? +Continue to [Create virtualhost](create-virtualhost.md). + +## FAQ + +### Do I need to edit the Windows `hosts` file for my virtualhosts? + +No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. + +### Can I use a domain that doesn't end in `.localhost`? + +The automatic routing described here relies on the `*.localhost` pattern. +Using a different TLD would require manually editing the Windows `hosts` file yourself. + +### How are the subdomain and domain parts of a virtualhost URL structured? + +The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. + +### Where do I actually create a virtualhost? + +This page only covers the concept. +See [Create virtualhost](create-virtualhost.md) for the steps to provision one. From 57e1afcc170e0ef061a4f39acff0553e2a5459dd Mon Sep 17 00:00:00 2001 From: bidi Date: Mon, 27 Jul 2026 15:18:07 +0300 Subject: [PATCH 3/6] added files for llms --- docs/book/v2/setup/installation.md | 2 +- public/llms-content/faq.md | 300 +++++ public/llms-content/llms-full.txt | 1041 +++++++++++++++++ public/llms-content/running.md | 80 ++ public/llms-content/setup/installation.md | 213 ++++ public/llms-content/setup/setup-packages.md | 160 +++ .../llms-content/setup/system-requirements.md | 95 ++ public/llms-content/terminal.md | 16 + .../virtualhosts/create-virtualhost.md | 98 ++ public/llms-content/virtualhosts/overview.md | 47 + 10 files changed, 2051 insertions(+), 1 deletion(-) create mode 100644 public/llms-content/faq.md create mode 100644 public/llms-content/llms-full.txt create mode 100644 public/llms-content/running.md create mode 100644 public/llms-content/setup/installation.md create mode 100644 public/llms-content/setup/setup-packages.md create mode 100644 public/llms-content/setup/system-requirements.md create mode 100644 public/llms-content/terminal.md create mode 100644 public/llms-content/virtualhosts/create-virtualhost.md create mode 100644 public/llms-content/virtualhosts/overview.md diff --git a/docs/book/v2/setup/installation.md b/docs/book/v2/setup/installation.md index b5fc7fc..e7097be 100644 --- a/docs/book/v2/setup/installation.md +++ b/docs/book/v2/setup/installation.md @@ -128,7 +128,7 @@ Enter new UNIX username: dotkernel. New password: ``` -Depending on the strength of your password, you might get a `BAD PASSWORD: ` message. +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 or continue with retyping your password. Next, you are asked to retype your password: diff --git a/public/llms-content/faq.md b/public/llms-content/faq.md new file mode 100644 index 0000000..61941c2 --- /dev/null +++ b/public/llms-content/faq.md @@ -0,0 +1,300 @@ +# AlmaLinux 10 Frequently asked questions + +Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your development environment. + +## 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.5`, `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 +* `php85`: switch to PHP 8.5 + +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: + +```terminaloutput +PHP 8.4.8 (cli) (built: Jun 3 2025 16:29:26) (NTS gcc x86_64) +Copyright (c) The PHP Group +Built by Remi's RPM repository #StandWithUkraine +Zend Engine v4.4.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: + +* `node24`: switch to Node.js 24 +* `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 +``` + +Depending on the selected Node.js version, the output should look similar to the below: + +```terminaloutput +v24.13.0 +``` + +Check npm version: + +```shell +npm -v +``` + +Depending on the current npm version, the output should look similar to the below: + +```terminaloutput +11.9.0 +``` + +## How do I fix common permission issues? + +If running your project, you encounter permission issues, follow the below steps. + +`chmod -R 777` grants read/write/execute access to everyone, which is only appropriate for a local development environment like this one. +Avoid carrying this habit into staging or production, where permissions should be scoped more narrowly (for example, to the web server's user/group). + +### 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.9.0 (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.9.0 2025-11-13 10:37:16 +PHP version 8.5.0 (/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 upgrade MariaDB? + +Initially, MariaDB was at version 11.4 LTS. +In case you want to upgrade to a different version, for instance [11.8 LTS](https://mariadb.org/11-8-is-lts/), use the below steps: + +* Open the MariaDB.repo file in any text editor. + +```shell +sudo nano /etc/yum.repos.d/MariaDB.repo +``` + +* Modify the **baseurl** variable to match the desired version, for instance `11.8` instead of `11.4`. +* Clean dnf cache + +```shell +sudo dnf clean all +``` + +* Stop MariaDB + +```shell +sudo systemctl stop mariadb +``` + +* Upgrade MariaDB + +```shell +sudo dnf update -y +``` + +* Start MariaDB + +```shell +sudo systemctl start mariadb +``` + +* Upgrade databases + +```shell +sudo mariadb-upgrade -uroot -p +``` + +* Restart MariaDB + +```shell +sudo systemctl restart mariadb +``` + +## How do I delete a virtualhost? + +If for whatever reason you want to delete a virtualhost, for instance `to-be-deleted.localhost` you need to do the following: + +* Delete the folder where the files are located + +```shell +sudo rm -rf /var/www/to-be-deleted.localhost +``` + +* Delete the Apache configuration file + +```shell +sudo rm -f /etc/httpd/sites-available/to-be-deleted.localhost.conf +``` + +* Delete the enabled site symlink + +```shell +sudo rm -f /etc/httpd/sites-enabled/to-be-deleted.localhost.conf +``` + +* Restart httpd server + +```shell +sudo systemctl restart httpd +``` + +## 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, create 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/public/llms-content/llms-full.txt b/public/llms-content/llms-full.txt new file mode 100644 index 0000000..38bdf11 --- /dev/null +++ b/public/llms-content/llms-full.txt @@ -0,0 +1,1041 @@ + + +# Terminal + +## Summary + +Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. + +If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). + +If you're not already using it, we recommend installing [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. + +Once your AlmaLinux 10 distro is installed, it gets its own dedicated tab profile in Windows Terminal (see [Running on WSL 2](running.md)), so every command in this guide (Windows and Linux alike) can be run from the same app. + +## Next step + +Continue to [System Requirements](setup/system-requirements.md) to check whether your machine is ready for WSL 2. + + + + +# System Requirements for AlmaLinux 10 on WSL 2 + +## Summary + +Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. + +If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). + +This is step 1 of 3 in setting up your development environment: **System Requirements** (this page) → [Install AlmaLinux 10](installation.md) → [Setup Packages](setup-packages.md). + +All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. + +## Minimum requirements + +Before installing WSL 2, make sure your machine meets the following: + +* Windows 10 version 1903 (build 18362) or higher, or Windows 11. +* A 64-bit processor with Second Level Address Translation (SLAT) support. +* Hardware virtualization enabled in your system's BIOS/UEFI (sometimes called `Intel VT-x`, `AMD-V`, or `SVM Mode`). +* At least 4 GB of RAM (8 GB or more recommended for running a full development stack comfortably). +* A few GB of free disk space for the distro plus additional space for your projects and databases. + +For the full, up-to-date list, see Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). + +## Check your WSL version + +Open `Windows Terminal` and execute the following command: + +```shell +wsl -v +``` + +The output should look similar to this (your version numbers will likely differ): + +```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 WSL 2 and can proceed to [install AlmaLinux 10](installation.md). +If it doesn't (for example, it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. + +## Install WSL 2 + +Once you've confirmed your machine meets the [minimum requirements](#minimum-requirements) above, 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 +``` + +Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). + +## FAQ + +### What if `wsl -v` shows WSL version 1 instead of 2? + +Run: + +```shell +wsl --set-default-version 2 +``` + +Then re-run `wsl -v` to confirm the version has switched. + +### What if the `OptionalFeatures` dialog doesn't show all required features? + +Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. + +### Do I need to restart my computer after enabling the Windows features? + +Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. + +### What if my machine doesn't meet the minimum requirements for WSL 2? + +Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. +If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). + + + + +# Install AlmaLinux 10 on WSL 2 + +## Summary + +Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. + +If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). + +This is step 2 of 3: [System Requirements](system-requirements.md) → **Install AlmaLinux 10** (this page) → [Setup Packages](setup-packages.md). + +All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. + +Before proceeding with the installation, we need to make sure that no other WSL 2 distribution (aka: _distro_) is running. +This is important because this installation will fail if required ports are already in use by another distro. + +The distro is downloaded over the internet, so make sure you have a stable connection. +Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer. + +Open `Windows Terminal`. + +## Stop other WSL 2 distros + +List all installed distros: + +```shell +wsl -l -v +``` + +If there is no other distro installed, you will see the below output (an empty list): + +```text + NAME STATE VERSION +``` + +In this case, you can jump to the [installation](#install-almalinux-10) section. + +If you have other distros installed, the output could look similar to the below: + +```text + NAME STATE VERSION + 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 it first by executing the below command, after replacing `` with the name of the distro you want to stop: + +```shell +wsl -t +``` + +Once you have stopped all distros, you can continue to the [installation](#install-almalinux-10) section. + +## Install AlmaLinux 10 + +List the available Linux 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`. + +If you try to install a distro that is already installed, the installation process will fail: + +```text +Downloading: AlmaLinux OS 10 +Installing: AlmaLinux OS 10 +A distribution with the supplied name already exists. Use --name to choose a different name. +Error code: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS +``` + +Install the **AlmaLinux 10** 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 **AlmaLinux 10**, 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 or 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 +[@ ]$ +``` + +At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). +Keep this window open and continue directly with [Setup Packages](setup-packages.md). +Its commands run inside AlmaLinux 10, not in Windows Terminal. +If you close this window, see [Running on WSL 2](../running.md) to reconnect. + +## Next step + +Continue to [Setup Packages](setup-packages.md) to install the required system packages and provision your development environment. + +## FAQ + +### What if the installation fails because a distro is already running? + +Make sure no other WSL 2 distro is running by checking: + +```shell +wsl -l -v +``` + +All distros must show **Stopped**. Stop any running distro with the below command before retrying the installation: + +```shell +wsl -t +``` + +### What if `AlmaLinux-10` is already installed? + +The installation will fail with `A distribution with the supplied name already exists`. +Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. + +### Does the username need to match my Windows username? + +No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. + +### What if I get a `BAD PASSWORD` message? + +This is just a strength warning. +Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. + +### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? + +Run the below command to see the current list of installable distros and their **NAME** values: + +```shell +wsl --list --online +``` + +### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? + +This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. +Revisit the [System Requirements](system-requirements.md) page and confirm both. +A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. + +### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? + +You don't need the Store for this step. +`wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. + +### How do I completely remove AlmaLinux-10 and start over? + +Unregister the distro, which deletes it and all its data, then reinstall it from scratch: + +```shell +wsl --unregister AlmaLinux-10 +``` + +Once unregistered, you can run `wsl --install -d AlmaLinux-10` again as described above. + + + + +# AlmaLinux 10 Setup + +## Summary + +Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. + +The instructions below also work without using WSL. + +This is step 3 of 3: [System Requirements](system-requirements.md) → [Install AlmaLinux 10](installation.md) → **Setup Packages** (this page). + +All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. +This is the same session left open at the end of the [installation](installation.md) step. +If you closed it, see [Running on WSL 2](../running.md) to reconnect first. + +Update/Upgrade system packages: + +```shell +sudo dnf upgrade -y +``` + +This step downloads packages over the internet and can take a few minutes depending on your connection speed and how many updates are pending. + +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 **AlmaLinux 10** password and hit `Enter`. + +Install system packages: + +```shell +sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y +``` + +`$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. +`dnf` verifies the package's GPG signature before installing it, same as any other package. + +Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections: + +```shell +sudo dnf install ansible-core -y +``` + +```shell +ansible-galaxy collection install community.general community.mysql +``` + +Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). +If either command fails or times out, check your network connection first. + +Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** 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: + +* `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10. +* `config.mariadb.root_password`: the password to set for MariaDB's `root` user (you'll use this to log into phpMyAdmin later). +* `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed. +* `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is. + +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 **AlmaLinux 10** 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: + +If you are not using WSL 2, test the below using your server's IP address instead of `localhost`. + +* [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 **AlmaLinux 10** development environment is ready to use. + +If you are using WSL 2, 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 **AlmaLinux 10**. + +## Next step + +Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project. + +## FAQ + +### What if `config.yml` doesn't exist yet? + +Duplicate the provided template by running: + +```shell +cp config.yml.dist config.yml +``` + +Then fill in the empty fields before running the playbook. + +### What if the Ansible playbook fails partway through? + +Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: + +```shell +ansible-playbook -i hosts install.yml --ask-become-pass +``` + +It is safe to re-run. + +### What if `ansible-galaxy collection install` fails or times out? + +This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. +Check your connection and re-run the command. +It's safe to run again even if some collections already installed successfully. + +### What if `http://localhost/` doesn't load after installation? + +If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. +Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. + +### How do I log into phpMyAdmin? + +Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. + +### Can I run this setup without WSL? + +Yes, the instructions work the same way on a non-WSL AlmaLinux system. +You can then skip the WSL-specific notes. + + + + +# Running AlmaLinux 10 on WSL 2 + +## Summary + +Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. + +If you are not using WSL 2, connect via SSH with [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/). + +Open `Windows Terminal`. + +Start **AlmaLinux 10** by executing: + +```shell +wsl -d AlmaLinux-10 +``` + +OR + +Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-10`. +This will open a new tab connected to **AlmaLinux 10**. + +To run your applications using WSL 2, you always need to be connected to your **AlmaLinux 10** distribution. +For this, all you need to do is to launch it from a terminal, file explorer or an IDE. +Once launched, you can close the tool you launched it from. +It will stay connected until you shut it down manually or reboot your computer. + +## Check if AlmaLinux 10 is running + +From Windows Terminal, execute: + +```shell +wsl -l -v +``` + +Look for the `AlmaLinux-10` row — its **STATE** column reads **Running** if it's currently active, or **Stopped** otherwise. + +## Shut down AlmaLinux 10 + +To stop just the AlmaLinux 10 distro, leaving any other distros untouched: + +```shell +wsl -t AlmaLinux-10 +``` + +To shut down all currently running WSL 2 distros at once: + +```shell +wsl --shutdown +``` + +## Next step + +Continue to [Virtualhosts](virtualhosts/overview.md) to start hosting your projects. + +## FAQ + +### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? + +Confirm it's actually installed by running: + +```shell +wsl -l -v +``` + +If it's missing from the list entirely, revisit [Install AlmaLinux 10](setup/installation.md). +Restarting Windows Terminal after installation also helps it pick up the new tab profile. + +### What if `wsl -d AlmaLinux-10` fails to start? + +Run the below command to confirm the distro is installed and check its current state: + +```shell +wsl -l -v +``` + +If another distro is using the same resources, stop it first with the below command, then retry: + +```shell +wsl -t +``` + + + + +# AlmaLinux 10 Overview + +## Summary + +Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. + +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 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 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. + +## Next step + +Ready to set one up? +Continue to [Create virtualhost](create-virtualhost.md). + +## FAQ + +### Do I need to edit the Windows `hosts` file for my virtualhosts? + +No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. + +### Can I use a domain that doesn't end in `.localhost`? + +The automatic routing described here relies on the `*.localhost` pattern. +Using a different TLD would require manually editing the Windows `hosts` file yourself. + +### How are the subdomain and domain parts of a virtualhost URL structured? + +The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. + +### Where do I actually create a virtualhost? + +This page only covers the concept. +See [Create virtualhost](create-virtualhost.md) for the steps to provision one. + + + + +# AlmaLinux 10 Create virtualhosts + +## Summary + +Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. + +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. + +This assumes you've already completed [Setup Packages](../setup/setup-packages.md). +Apache must already be installed before virtualhosts can be created. + +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. + +Virtualhost names should be valid hostnames (lowercase letters, numbers, and hyphens) ending in `.localhost`, for example `api.dotkernel.localhost`. +Avoid spaces or other special characters. + +You can come back and add more virtualhosts at any time: add new lines under `virtualhosts` and re-run the playbook. +Existing virtualhosts are left untouched. + +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 **AlmaLinux 10** password, iterate over the list of configured, 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`. + +A freshly created virtualhost only has an empty `html` directory - `html/public` doesn't exist yet. +Visiting the virtualhost's URL in your browser will show an error until you place a project there, this is expected. + +Apache logs for each virtualhost are stored separately, for example `/var/www/example.localhost/log/error.log` and `/var/www/example.localhost/log/requests.log`. +Check these first if something isn't working as expected. + +## Good to know + +* To run your installed projects, you need to start **AlmaLinux 10** 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). + +## FAQ + +### What if I don't have a `config.yml` file yet? + +Duplicate the provided template by running the below command inside `development/wsl`: + +```shell +cp config.yml.dist config.yml +``` + +Then add your virtualhosts under the `virtualhosts` key. + +### What happens if I list a virtualhost that already exists? + +It will simply be skipped. +Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from `config.yml`. + +### Where should I put my project's files? + +Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. +The document root is set to the `public` subdirectory of that location, for example `/var/www/example.localhost/html/public`. + +### How do I make the DocumentRoot point directly to `html` instead of `html/public`? + +Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. + +### How do I access my virtualhost if AlmaLinux 10 isn't running? + +You need to start **AlmaLinux 10** first. +Your virtualhosts are only reachable while the distro is running. + +### What if I hit permission errors when writing to my project's files? + +See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. + +### How do I delete a virtualhost I no longer need? + +See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. + + + + +# AlmaLinux 10 Frequently asked questions + +Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your development environment. + +## 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.5`, `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 +* `php85`: switch to PHP 8.5 + +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: + +```terminaloutput +PHP 8.4.8 (cli) (built: Jun 3 2025 16:29:26) (NTS gcc x86_64) +Copyright (c) The PHP Group +Built by Remi's RPM repository #StandWithUkraine +Zend Engine v4.4.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: + +* `node24`: switch to Node.js 24 +* `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 +``` + +Depending on the selected Node.js version, the output should look similar to the below: + +```terminaloutput +v24.13.0 +``` + +Check npm version: + +```shell +npm -v +``` + +Depending on the current npm version, the output should look similar to the below: + +```terminaloutput +11.9.0 +``` + +## How do I fix common permission issues? + +If running your project, you encounter permission issues, follow the below steps. + +`chmod -R 777` grants read/write/execute access to everyone, which is only appropriate for a local development environment like this one. +Avoid carrying this habit into staging or production, where permissions should be scoped more narrowly (for example, to the web server's user/group). + +### 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.9.0 (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.9.0 2025-11-13 10:37:16 +PHP version 8.5.0 (/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 upgrade MariaDB? + +Initially, MariaDB was at version 11.4 LTS. +In case you want to upgrade to a different version, for instance [11.8 LTS](https://mariadb.org/11-8-is-lts/), use the below steps: + +* Open the MariaDB.repo file in any text editor. + +```shell +sudo nano /etc/yum.repos.d/MariaDB.repo +``` + +* Modify the **baseurl** variable to match the desired version, for instance `11.8` instead of `11.4`. +* Clean dnf cache + +```shell +sudo dnf clean all +``` + +* Stop MariaDB + +```shell +sudo systemctl stop mariadb +``` + +* Upgrade MariaDB + +```shell +sudo dnf update -y +``` + +* Start MariaDB + +```shell +sudo systemctl start mariadb +``` + +* Upgrade databases + +```shell +sudo mariadb-upgrade -uroot -p +``` + +* Restart MariaDB + +```shell +sudo systemctl restart mariadb +``` + +## How do I delete a virtualhost? + +If for whatever reason you want to delete a virtualhost, for instance `to-be-deleted.localhost` you need to do the following: + +* Delete the folder where the files are located + +```shell +sudo rm -rf /var/www/to-be-deleted.localhost +``` + +* Delete the Apache configuration file + +```shell +sudo rm -f /etc/httpd/sites-available/to-be-deleted.localhost.conf +``` + +* Delete the enabled site symlink + +```shell +sudo rm -f /etc/httpd/sites-enabled/to-be-deleted.localhost.conf +``` + +* Restart httpd server + +```shell +sudo systemctl restart httpd +``` + +## 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, create 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/public/llms-content/running.md b/public/llms-content/running.md new file mode 100644 index 0000000..6fc42ad --- /dev/null +++ b/public/llms-content/running.md @@ -0,0 +1,80 @@ +# Running AlmaLinux 10 on WSL 2 + +## Summary + +Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. + +If you are not using WSL 2, connect via SSH with [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/). + +Open `Windows Terminal`. + +Start **AlmaLinux 10** by executing: + +```shell +wsl -d AlmaLinux-10 +``` + +OR + +Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-10`. +This will open a new tab connected to **AlmaLinux 10**. + +To run your applications using WSL 2, you always need to be connected to your **AlmaLinux 10** distribution. +For this, all you need to do is to launch it from a terminal, file explorer or an IDE. +Once launched, you can close the tool you launched it from. +It will stay connected until you shut it down manually or reboot your computer. + +## Check if AlmaLinux 10 is running + +From Windows Terminal, execute: + +```shell +wsl -l -v +``` + +Look for the `AlmaLinux-10` row — its **STATE** column reads **Running** if it's currently active, or **Stopped** otherwise. + +## Shut down AlmaLinux 10 + +To stop just the AlmaLinux 10 distro, leaving any other distros untouched: + +```shell +wsl -t AlmaLinux-10 +``` + +To shut down all currently running WSL 2 distros at once: + +```shell +wsl --shutdown +``` + +## Next step + +Continue to [Virtualhosts](virtualhosts/overview.md) to start hosting your projects. + +## FAQ + +### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? + +Confirm it's actually installed by running: + +```shell +wsl -l -v +``` + +If it's missing from the list entirely, revisit [Install AlmaLinux 10](setup/installation.md). +Restarting Windows Terminal after installation also helps it pick up the new tab profile. + +### What if `wsl -d AlmaLinux-10` fails to start? + +Run the below command to confirm the distro is installed and check its current state: + +```shell +wsl -l -v +``` + +If another distro is using the same resources, stop it first with the below command, then retry: + +```shell +wsl -t +``` diff --git a/public/llms-content/setup/installation.md b/public/llms-content/setup/installation.md new file mode 100644 index 0000000..8e557fe --- /dev/null +++ b/public/llms-content/setup/installation.md @@ -0,0 +1,213 @@ +# Install AlmaLinux 10 on WSL 2 + +## Summary + +Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. + +If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). + +This is step 2 of 3: [System Requirements](system-requirements.md) → **Install AlmaLinux 10** (this page) → [Setup Packages](setup-packages.md). + +All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. + +Before proceeding with the installation, we need to make sure that no other WSL 2 distribution (aka: _distro_) is running. +This is important because this installation will fail if required ports are already in use by another distro. + +The distro is downloaded over the internet, so make sure you have a stable connection. +Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer. + +Open `Windows Terminal`. + +## Stop other WSL 2 distros + +List all installed distros: + +```shell +wsl -l -v +``` + +If there is no other distro installed, you will see the below output (an empty list): + +```text + NAME STATE VERSION +``` + +In this case, you can jump to the [installation](#install-almalinux-10) section. + +If you have other distros installed, the output could look similar to the below: + +```text + NAME STATE VERSION + 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 it first by executing the below command, after replacing `` with the name of the distro you want to stop: + +```shell +wsl -t +``` + +Once you have stopped all distros, you can continue to the [installation](#install-almalinux-10) section. + +## Install AlmaLinux 10 + +List the available Linux 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`. + +If you try to install a distro that is already installed, the installation process will fail: + +```text +Downloading: AlmaLinux OS 10 +Installing: AlmaLinux OS 10 +A distribution with the supplied name already exists. Use --name to choose a different name. +Error code: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS +``` + +Install the **AlmaLinux 10** 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 **AlmaLinux 10**, 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 or 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 +[@ ]$ +``` + +At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). +Keep this window open and continue directly with [Setup Packages](setup-packages.md). +Its commands run inside AlmaLinux 10, not in Windows Terminal. +If you close this window, see [Running on WSL 2](../running.md) to reconnect. + +## Next step + +Continue to [Setup Packages](setup-packages.md) to install the required system packages and provision your development environment. + +## FAQ + +### What if the installation fails because a distro is already running? + +Make sure no other WSL 2 distro is running by checking: + +```shell +wsl -l -v +``` + +All distros must show **Stopped**. Stop any running distro with the below command before retrying the installation: + +```shell +wsl -t +``` + +### What if `AlmaLinux-10` is already installed? + +The installation will fail with `A distribution with the supplied name already exists`. +Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. + +### Does the username need to match my Windows username? + +No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. + +### What if I get a `BAD PASSWORD` message? + +This is just a strength warning. +Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. + +### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? + +Run the below command to see the current list of installable distros and their **NAME** values: + +```shell +wsl --list --online +``` + +### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? + +This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. +Revisit the [System Requirements](system-requirements.md) page and confirm both. +A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. + +### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? + +You don't need the Store for this step. +`wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. + +### How do I completely remove AlmaLinux-10 and start over? + +Unregister the distro, which deletes it and all its data, then reinstall it from scratch: + +```shell +wsl --unregister AlmaLinux-10 +``` + +Once unregistered, you can run `wsl --install -d AlmaLinux-10` again as described above. diff --git a/public/llms-content/setup/setup-packages.md b/public/llms-content/setup/setup-packages.md new file mode 100644 index 0000000..784defd --- /dev/null +++ b/public/llms-content/setup/setup-packages.md @@ -0,0 +1,160 @@ +# AlmaLinux 10 Setup + +## Summary + +Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. + +The instructions below also work without using WSL. + +This is step 3 of 3: [System Requirements](system-requirements.md) → [Install AlmaLinux 10](installation.md) → **Setup Packages** (this page). + +All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. +This is the same session left open at the end of the [installation](installation.md) step. +If you closed it, see [Running on WSL 2](../running.md) to reconnect first. + +Update/Upgrade system packages: + +```shell +sudo dnf upgrade -y +``` + +This step downloads packages over the internet and can take a few minutes depending on your connection speed and how many updates are pending. + +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 **AlmaLinux 10** password and hit `Enter`. + +Install system packages: + +```shell +sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y +``` + +`$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. +`dnf` verifies the package's GPG signature before installing it, same as any other package. + +Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections: + +```shell +sudo dnf install ansible-core -y +``` + +```shell +ansible-galaxy collection install community.general community.mysql +``` + +Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). +If either command fails or times out, check your network connection first. + +Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** 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: + +* `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10. +* `config.mariadb.root_password`: the password to set for MariaDB's `root` user (you'll use this to log into phpMyAdmin later). +* `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed. +* `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is. + +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 **AlmaLinux 10** 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: + +If you are not using WSL 2, test the below using your server's IP address instead of `localhost`. + +* [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 **AlmaLinux 10** development environment is ready to use. + +If you are using WSL 2, 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 **AlmaLinux 10**. + +## Next step + +Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project. + +## FAQ + +### What if `config.yml` doesn't exist yet? + +Duplicate the provided template by running: + +```shell +cp config.yml.dist config.yml +``` + +Then fill in the empty fields before running the playbook. + +### What if the Ansible playbook fails partway through? + +Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: + +```shell +ansible-playbook -i hosts install.yml --ask-become-pass +``` + +It is safe to re-run. + +### What if `ansible-galaxy collection install` fails or times out? + +This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. +Check your connection and re-run the command. +It's safe to run again even if some collections already installed successfully. + +### What if `http://localhost/` doesn't load after installation? + +If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. +Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. + +### How do I log into phpMyAdmin? + +Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. + +### Can I run this setup without WSL? + +Yes, the instructions work the same way on a non-WSL AlmaLinux system. +You can then skip the WSL-specific notes. diff --git a/public/llms-content/setup/system-requirements.md b/public/llms-content/setup/system-requirements.md new file mode 100644 index 0000000..63024ec --- /dev/null +++ b/public/llms-content/setup/system-requirements.md @@ -0,0 +1,95 @@ +# System Requirements for AlmaLinux 10 on WSL 2 + +## Summary + +Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. + +If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). + +This is step 1 of 3 in setting up your development environment: **System Requirements** (this page) → [Install AlmaLinux 10](installation.md) → [Setup Packages](setup-packages.md). + +All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. + +## Minimum requirements + +Before installing WSL 2, make sure your machine meets the following: + +* Windows 10 version 1903 (build 18362) or higher, or Windows 11. +* A 64-bit processor with Second Level Address Translation (SLAT) support. +* Hardware virtualization enabled in your system's BIOS/UEFI (sometimes called `Intel VT-x`, `AMD-V`, or `SVM Mode`). +* At least 4 GB of RAM (8 GB or more recommended for running a full development stack comfortably). +* A few GB of free disk space for the distro plus additional space for your projects and databases. + +For the full, up-to-date list, see Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). + +## Check your WSL version + +Open `Windows Terminal` and execute the following command: + +```shell +wsl -v +``` + +The output should look similar to this (your version numbers will likely differ): + +```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 WSL 2 and can proceed to [install AlmaLinux 10](installation.md). +If it doesn't (for example, it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. + +## Install WSL 2 + +Once you've confirmed your machine meets the [minimum requirements](#minimum-requirements) above, 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 +``` + +Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). + +## FAQ + +### What if `wsl -v` shows WSL version 1 instead of 2? + +Run: + +```shell +wsl --set-default-version 2 +``` + +Then re-run `wsl -v` to confirm the version has switched. + +### What if the `OptionalFeatures` dialog doesn't show all required features? + +Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. + +### Do I need to restart my computer after enabling the Windows features? + +Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. + +### What if my machine doesn't meet the minimum requirements for WSL 2? + +Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. +If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). diff --git a/public/llms-content/terminal.md b/public/llms-content/terminal.md new file mode 100644 index 0000000..2250ff6 --- /dev/null +++ b/public/llms-content/terminal.md @@ -0,0 +1,16 @@ +# Terminal + +## Summary + +Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. + +If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). + +If you're not already using it, we recommend installing [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. + +Once your AlmaLinux 10 distro is installed, it gets its own dedicated tab profile in Windows Terminal (see [Running on WSL 2](running.md)), so every command in this guide (Windows and Linux alike) can be run from the same app. + +## Next step + +Continue to [System Requirements](setup/system-requirements.md) to check whether your machine is ready for WSL 2. diff --git a/public/llms-content/virtualhosts/create-virtualhost.md b/public/llms-content/virtualhosts/create-virtualhost.md new file mode 100644 index 0000000..d87bcac --- /dev/null +++ b/public/llms-content/virtualhosts/create-virtualhost.md @@ -0,0 +1,98 @@ +# AlmaLinux 10 Create virtualhosts + +## Summary + +Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. + +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. + +This assumes you've already completed [Setup Packages](../setup/setup-packages.md). +Apache must already be installed before virtualhosts can be created. + +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. + +Virtualhost names should be valid hostnames (lowercase letters, numbers, and hyphens) ending in `.localhost`, for example `api.dotkernel.localhost`. +Avoid spaces or other special characters. + +You can come back and add more virtualhosts at any time: add new lines under `virtualhosts` and re-run the playbook. +Existing virtualhosts are left untouched. + +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 **AlmaLinux 10** password, iterate over the list of configured, 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`. + +A freshly created virtualhost only has an empty `html` directory - `html/public` doesn't exist yet. +Visiting the virtualhost's URL in your browser will show an error until you place a project there, this is expected. + +Apache logs for each virtualhost are stored separately, for example `/var/www/example.localhost/log/error.log` and `/var/www/example.localhost/log/requests.log`. +Check these first if something isn't working as expected. + +## Good to know + +* To run your installed projects, you need to start **AlmaLinux 10** 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). + +## FAQ + +### What if I don't have a `config.yml` file yet? + +Duplicate the provided template by running the below command inside `development/wsl`: + +```shell +cp config.yml.dist config.yml +``` + +Then add your virtualhosts under the `virtualhosts` key. + +### What happens if I list a virtualhost that already exists? + +It will simply be skipped. +Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from `config.yml`. + +### Where should I put my project's files? + +Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. +The document root is set to the `public` subdirectory of that location, for example `/var/www/example.localhost/html/public`. + +### How do I make the DocumentRoot point directly to `html` instead of `html/public`? + +Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. + +### How do I access my virtualhost if AlmaLinux 10 isn't running? + +You need to start **AlmaLinux 10** first. +Your virtualhosts are only reachable while the distro is running. + +### What if I hit permission errors when writing to my project's files? + +See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. + +### How do I delete a virtualhost I no longer need? + +See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. diff --git a/public/llms-content/virtualhosts/overview.md b/public/llms-content/virtualhosts/overview.md new file mode 100644 index 0000000..af6c5c1 --- /dev/null +++ b/public/llms-content/virtualhosts/overview.md @@ -0,0 +1,47 @@ +# AlmaLinux 10 Overview + +## Summary + +Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. + +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 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 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. + +## Next step + +Ready to set one up? +Continue to [Create virtualhost](create-virtualhost.md). + +## FAQ + +### Do I need to edit the Windows `hosts` file for my virtualhosts? + +No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. + +### Can I use a domain that doesn't end in `.localhost`? + +The automatic routing described here relies on the `*.localhost` pattern. +Using a different TLD would require manually editing the Windows `hosts` file yourself. + +### How are the subdomain and domain parts of a virtualhost URL structured? + +The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. + +### Where do I actually create a virtualhost? + +This page only covers the concept. +See [Create virtualhost](create-virtualhost.md) for the steps to provision one. From 6782d4615a9f73d53bb6c35ad4403d0a90975bb2 Mon Sep 17 00:00:00 2001 From: bidi Date: Mon, 27 Jul 2026 17:59:53 +0300 Subject: [PATCH 4/6] updated llms content --- public/llms-content/faq.md | 50 ++-- public/llms-content/llms-full.txt | 242 +++++++++--------- public/llms-content/running.md | 62 +---- public/llms-content/setup/installation.md | 163 +----------- public/llms-content/setup/setup-packages.md | 127 +-------- .../llms-content/setup/system-requirements.md | 79 +----- public/llms-content/terminal.md | 25 +- .../virtualhosts/create-virtualhost.md | 68 +---- public/llms-content/virtualhosts/overview.md | 36 +-- 9 files changed, 232 insertions(+), 620 deletions(-) diff --git a/public/llms-content/faq.md b/public/llms-content/faq.md index 61941c2..bca3b25 100644 --- a/public/llms-content/faq.md +++ b/public/llms-content/faq.md @@ -1,8 +1,22 @@ +--- +title: AlmaLinux 10 Frequently asked questions +description: Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your AlmaLinux 10 development environment. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/faq" +category: "Development" +language: "en" +--- + # AlmaLinux 10 Frequently asked questions +## TL;DR + Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your development environment. -## How do I switch to a different version of PHP? +## FAQ + +### How do I switch to a different version of PHP? Execute the following command: @@ -36,7 +50,7 @@ Built by Remi's RPM repository #StandWithUkraine Zend Engine v4.4.8, Copyright (c) Zend Technologies ``` -## How do I switch to a different version of Node.js? +### How do I switch to a different version of Node.js? Execute the following commands: @@ -80,14 +94,14 @@ Depending on the current npm version, the output should look similar to the belo 11.9.0 ``` -## How do I fix common permission issues? +### How do I fix common permission issues? If running your project, you encounter permission issues, follow the below steps. `chmod -R 777` grants read/write/execute access to everyone, which is only appropriate for a local development environment like this one. Avoid carrying this habit into staging or production, where permissions should be scoped more narrowly (for example, to the web server's user/group). -### Error +#### Error PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data" is not writable... @@ -95,52 +109,52 @@ PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache/doctrine" is not writable... -### Solution +#### Solution ```shell chmod -R 777 data ``` -### Error +#### Error PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not writable... -### Solution +#### Solution ```shell chmod -R 777 public/uploads ``` -### Error +#### Error PHP Fatal error: Uncaught ErrorException: fopen(``/log/error-log-yyyy-mm-dd.log): Failed to open stream: Permission denied... -### Solution +#### Solution ```shell chmod -R 777 log ``` -## Where are the error log files? +### 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 +#### Apache log files ```text /var/log/httpd/error_log ``` -### PHP-FPM log files +#### PHP-FPM log files ```text /var/log/php-fpm/error.log /var/log/php-fpm/www-error.log ``` -## How do I update Composer? +### How do I update Composer? Before updating, check your current Composer version by executing: @@ -184,7 +198,7 @@ PHP version 8.5.0 (/usr/bin/php) Run the "diagnose" command to get more detailed diagnostics output. ``` -## How do I update phpMyAdmin? +### 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: @@ -192,7 +206,7 @@ Being installed as a system package, it can be updated using the command which u sudo dnf upgrade -y ``` -## How do I upgrade MariaDB? +### How do I upgrade MariaDB? Initially, MariaDB was at version 11.4 LTS. In case you want to upgrade to a different version, for instance [11.8 LTS](https://mariadb.org/11-8-is-lts/), use the below steps: @@ -240,7 +254,7 @@ sudo mariadb-upgrade -uroot -p sudo systemctl restart mariadb ``` -## How do I delete a virtualhost? +### How do I delete a virtualhost? If for whatever reason you want to delete a virtualhost, for instance `to-be-deleted.localhost` you need to do the following: @@ -268,7 +282,7 @@ sudo rm -f /etc/httpd/sites-enabled/to-be-deleted.localhost.conf sudo systemctl restart httpd ``` -## How do I create command aliases? +### How do I create command aliases? From either your terminal or file explorer, navigate to your home directory (`/home//`). @@ -285,7 +299,7 @@ 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 +#### Example ```text alias list_files="ls -Al" diff --git a/public/llms-content/llms-full.txt b/public/llms-content/llms-full.txt index 38bdf11..06579f4 100644 --- a/public/llms-content/llms-full.txt +++ b/public/llms-content/llms-full.txt @@ -1,8 +1,12 @@ - +# DotKernel Development Environment (AlmaLinux 10 on WSL 2) -# Terminal +> A collection of Ansible playbooks and documentation for provisioning a local AlmaLinux 10 development environment on Windows via WSL 2. It covers installing Windows Terminal, setting up WSL 2, provisioning the full stack (PHP, Node.js, MariaDB, Apache, phpMyAdmin, Composer) with Ansible, and creating per-project Apache virtualhosts under `*.localhost` domains. -## Summary +## Introduction + +### Terminal + +#### Summary Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. @@ -13,16 +17,15 @@ It is a modern tool that incorporates the power of multiple already known comman Once your AlmaLinux 10 distro is installed, it gets its own dedicated tab profile in Windows Terminal (see [Running on WSL 2](running.md)), so every command in this guide (Windows and Linux alike) can be run from the same app. -## Next step +#### Next step Continue to [System Requirements](setup/system-requirements.md) to check whether your machine is ready for WSL 2. +## Setup - +### System Requirements for AlmaLinux 10 on WSL 2 -# System Requirements for AlmaLinux 10 on WSL 2 - -## Summary +#### Summary Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. @@ -32,7 +35,7 @@ This is step 1 of 3 in setting up your development environment: **System Require All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. -## Minimum requirements +#### Minimum requirements Before installing WSL 2, make sure your machine meets the following: @@ -44,7 +47,7 @@ Before installing WSL 2, make sure your machine meets the following: For the full, up-to-date list, see Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). -## Check your WSL version +#### Check your WSL version Open `Windows Terminal` and execute the following command: @@ -67,9 +70,9 @@ Windows version: 10.0.22631.3737 If the output starts with `WSL version: 2.x.x.x`, you are ready to use WSL 2 and can proceed to [install AlmaLinux 10](installation.md). If it doesn't (for example, it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. -## Install WSL 2 +#### Install WSL 2 -Once you've confirmed your machine meets the [minimum requirements](#minimum-requirements) above, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`. +Once you've confirmed your machine meets the minimum requirements above, 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): @@ -89,11 +92,11 @@ Make sure that version `2` of WSL is set as default by executing the below comma wsl --set-default-version 2 ``` -Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). +Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` (in the same format shown above), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). -## FAQ +#### FAQ -### What if `wsl -v` shows WSL version 1 instead of 2? +##### What if `wsl -v` shows WSL version 1 instead of 2? Run: @@ -103,25 +106,22 @@ wsl --set-default-version 2 Then re-run `wsl -v` to confirm the version has switched. -### What if the `OptionalFeatures` dialog doesn't show all required features? +##### What if the `OptionalFeatures` dialog doesn't show all required features? Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. -### Do I need to restart my computer after enabling the Windows features? +##### Do I need to restart my computer after enabling the Windows features? Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. -### What if my machine doesn't meet the minimum requirements for WSL 2? +##### What if my machine doesn't meet the minimum requirements for WSL 2? -Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. +Double-check the minimum requirements above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). +### Install AlmaLinux 10 on WSL 2 - - -# Install AlmaLinux 10 on WSL 2 - -## Summary +#### Summary Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. @@ -139,7 +139,7 @@ Depending on your connection speed, the download can take anywhere from a couple Open `Windows Terminal`. -## Stop other WSL 2 distros +#### Stop other WSL 2 distros List all installed distros: @@ -153,7 +153,7 @@ 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-almalinux-10) section. +In this case, you can jump to the installation section below. If you have other distros installed, the output could look similar to the below: @@ -170,9 +170,9 @@ If any of them reads **Running**, you must stop it first by executing the below wsl -t ``` -Once you have stopped all distros, you can continue to the [installation](#install-almalinux-10) section. +Once you have stopped all distros, you can continue to the installation section below. -## Install AlmaLinux 10 +#### Install AlmaLinux 10 List the available Linux distros by executing: @@ -270,13 +270,13 @@ Keep this window open and continue directly with [Setup Packages](setup-packages Its commands run inside AlmaLinux 10, not in Windows Terminal. If you close this window, see [Running on WSL 2](../running.md) to reconnect. -## Next step +#### Next step Continue to [Setup Packages](setup-packages.md) to install the required system packages and provision your development environment. -## FAQ +#### FAQ -### What if the installation fails because a distro is already running? +##### What if the installation fails because a distro is already running? Make sure no other WSL 2 distro is running by checking: @@ -290,21 +290,21 @@ All distros must show **Stopped**. Stop any running distro with the below comman wsl -t ``` -### What if `AlmaLinux-10` is already installed? +##### What if `AlmaLinux-10` is already installed? The installation will fail with `A distribution with the supplied name already exists`. Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. -### Does the username need to match my Windows username? +##### Does the username need to match my Windows username? No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. -### What if I get a `BAD PASSWORD` message? +##### What if I get a `BAD PASSWORD` message? This is just a strength warning. Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. -### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? +##### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? Run the below command to see the current list of installable distros and their **NAME** values: @@ -312,18 +312,18 @@ Run the below command to see the current list of installable distros and their * wsl --list --online ``` -### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? +##### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. -Revisit the [System Requirements](system-requirements.md) page and confirm both. +Revisit the System Requirements page and confirm both. A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. -### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? +##### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? You don't need the Store for this step. `wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. -### How do I completely remove AlmaLinux-10 and start over? +##### How do I completely remove AlmaLinux-10 and start over? Unregister the distro, which deletes it and all its data, then reinstall it from scratch: @@ -333,12 +333,9 @@ wsl --unregister AlmaLinux-10 Once unregistered, you can run `wsl --install -d AlmaLinux-10` again as described above. +### AlmaLinux 10 Setup - - -# AlmaLinux 10 Setup - -## Summary +#### Summary Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. @@ -451,13 +448,13 @@ The installation is complete, your **AlmaLinux 10** development environment is r If you are using WSL 2, 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 **AlmaLinux 10**. -## Next step +#### Next step Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project. -## FAQ +#### FAQ -### What if `config.yml` doesn't exist yet? +##### What if `config.yml` doesn't exist yet? Duplicate the provided template by running: @@ -467,7 +464,7 @@ cp config.yml.dist config.yml Then fill in the empty fields before running the playbook. -### What if the Ansible playbook fails partway through? +##### What if the Ansible playbook fails partway through? Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: @@ -477,32 +474,31 @@ ansible-playbook -i hosts install.yml --ask-become-pass It is safe to re-run. -### What if `ansible-galaxy collection install` fails or times out? +##### What if `ansible-galaxy collection install` fails or times out? This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. Check your connection and re-run the command. It's safe to run again even if some collections already installed successfully. -### What if `http://localhost/` doesn't load after installation? +##### What if `http://localhost/` doesn't load after installation? If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. -### How do I log into phpMyAdmin? +##### How do I log into phpMyAdmin? Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. -### Can I run this setup without WSL? +##### Can I run this setup without WSL? Yes, the instructions work the same way on a non-WSL AlmaLinux system. You can then skip the WSL-specific notes. +## Guides - +### Running AlmaLinux 10 on WSL 2 -# Running AlmaLinux 10 on WSL 2 - -## Summary +#### Summary Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. @@ -526,7 +522,7 @@ For this, all you need to do is to launch it from a terminal, file explorer or a Once launched, you can close the tool you launched it from. It will stay connected until you shut it down manually or reboot your computer. -## Check if AlmaLinux 10 is running +#### Check if AlmaLinux 10 is running From Windows Terminal, execute: @@ -536,7 +532,7 @@ wsl -l -v Look for the `AlmaLinux-10` row — its **STATE** column reads **Running** if it's currently active, or **Stopped** otherwise. -## Shut down AlmaLinux 10 +#### Shut down AlmaLinux 10 To stop just the AlmaLinux 10 distro, leaving any other distros untouched: @@ -550,13 +546,13 @@ To shut down all currently running WSL 2 distros at once: wsl --shutdown ``` -## Next step +#### Next step Continue to [Virtualhosts](virtualhosts/overview.md) to start hosting your projects. -## FAQ +#### FAQ -### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? +##### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? Confirm it's actually installed by running: @@ -567,7 +563,7 @@ wsl -l -v If it's missing from the list entirely, revisit [Install AlmaLinux 10](setup/installation.md). Restarting Windows Terminal after installation also helps it pick up the new tab profile. -### What if `wsl -d AlmaLinux-10` fails to start? +##### What if `wsl -d AlmaLinux-10` fails to start? Run the below command to confirm the distro is installed and check its current state: @@ -581,12 +577,9 @@ If another distro is using the same resources, stop it first with the below comm wsl -t ``` +### AlmaLinux 10 Overview - - -# AlmaLinux 10 Overview - -## Summary +#### Summary Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. @@ -607,37 +600,34 @@ In the above example, the URLs are built like this: 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. -## Next step +#### Next step Ready to set one up? Continue to [Create virtualhost](create-virtualhost.md). -## FAQ +#### FAQ -### Do I need to edit the Windows `hosts` file for my virtualhosts? +##### Do I need to edit the Windows `hosts` file for my virtualhosts? No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. -### Can I use a domain that doesn't end in `.localhost`? +##### Can I use a domain that doesn't end in `.localhost`? The automatic routing described here relies on the `*.localhost` pattern. Using a different TLD would require manually editing the Windows `hosts` file yourself. -### How are the subdomain and domain parts of a virtualhost URL structured? +##### How are the subdomain and domain parts of a virtualhost URL structured? The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. -### Where do I actually create a virtualhost? +##### Where do I actually create a virtualhost? This page only covers the concept. See [Create virtualhost](create-virtualhost.md) for the steps to provision one. +### AlmaLinux 10 Create virtualhosts - - -# AlmaLinux 10 Create virtualhosts - -## Summary +#### Summary Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. @@ -686,7 +676,7 @@ Visiting the virtualhost's URL in your browser will show an error until you plac Apache logs for each virtualhost are stored separately, for example `/var/www/example.localhost/log/error.log` and `/var/www/example.localhost/log/requests.log`. Check these first if something isn't working as expected. -## Good to know +#### Good to know * To run your installed projects, you need to start **AlmaLinux 10** first. * If you work with virtualhosts, your projects are created under `/var/www/`. @@ -695,9 +685,9 @@ Check these first if something isn't working as expected. * 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). -## FAQ +#### FAQ -### What if I don't have a `config.yml` file yet? +##### What if I don't have a `config.yml` file yet? Duplicate the provided template by running the below command inside `development/wsl`: @@ -707,41 +697,40 @@ cp config.yml.dist config.yml Then add your virtualhosts under the `virtualhosts` key. -### What happens if I list a virtualhost that already exists? +##### What happens if I list a virtualhost that already exists? It will simply be skipped. Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from `config.yml`. -### Where should I put my project's files? +##### Where should I put my project's files? Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. The document root is set to the `public` subdirectory of that location, for example `/var/www/example.localhost/html/public`. -### How do I make the DocumentRoot point directly to `html` instead of `html/public`? +##### How do I make the DocumentRoot point directly to `html` instead of `html/public`? Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. -### How do I access my virtualhost if AlmaLinux 10 isn't running? +##### How do I access my virtualhost if AlmaLinux 10 isn't running? You need to start **AlmaLinux 10** first. Your virtualhosts are only reachable while the distro is running. -### What if I hit permission errors when writing to my project's files? - -See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. +##### What if I hit permission errors when writing to my project's files? -### How do I delete a virtualhost I no longer need? +See the permission issues guide in the FAQ section below. -See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. +##### How do I delete a virtualhost I no longer need? +See "How do I delete a virtualhost?" in the FAQ section below. - +## FAQ -# AlmaLinux 10 Frequently asked questions +### AlmaLinux 10 Frequently asked questions Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your development environment. -## How do I switch to a different version of PHP? +#### How do I switch to a different version of PHP? Execute the following command: @@ -768,14 +757,14 @@ php -v Depending on the selected PHP version, the output should look similar to the below: -```terminaloutput +```text PHP 8.4.8 (cli) (built: Jun 3 2025 16:29:26) (NTS gcc x86_64) Copyright (c) The PHP Group Built by Remi's RPM repository #StandWithUkraine Zend Engine v4.4.8, Copyright (c) Zend Technologies ``` -## How do I switch to a different version of Node.js? +#### How do I switch to a different version of Node.js? Execute the following commands: @@ -803,7 +792,7 @@ node -v Depending on the selected Node.js version, the output should look similar to the below: -```terminaloutput +```text v24.13.0 ``` @@ -815,18 +804,18 @@ npm -v Depending on the current npm version, the output should look similar to the below: -```terminaloutput +```text 11.9.0 ``` -## How do I fix common permission issues? +#### How do I fix common permission issues? If running your project, you encounter permission issues, follow the below steps. `chmod -R 777` grants read/write/execute access to everyone, which is only appropriate for a local development environment like this one. Avoid carrying this habit into staging or production, where permissions should be scoped more narrowly (for example, to the web server's user/group). -### Error +##### Error: `data` directory not writable PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data" is not writable... @@ -834,52 +823,52 @@ PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache/doctrine" is not writable... -### Solution +Solution: ```shell chmod -R 777 data ``` -### Error +##### Error: `public/uploads` directory not writable PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not writable... -### Solution +Solution: ```shell chmod -R 777 public/uploads ``` -### Error +##### Error: `log` directory not writable PHP Fatal error: Uncaught ErrorException: fopen(``/log/error-log-yyyy-mm-dd.log): Failed to open stream: Permission denied... -### Solution +Solution: ```shell chmod -R 777 log ``` -## Where are the error log files? +#### 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 +Apache log files: ```text /var/log/httpd/error_log ``` -### PHP-FPM log files +PHP-FPM log files: ```text /var/log/php-fpm/error.log /var/log/php-fpm/www-error.log ``` -## How do I update Composer? +#### How do I update Composer? Before updating, check your current Composer version by executing: @@ -923,7 +912,7 @@ PHP version 8.5.0 (/usr/bin/php) Run the "diagnose" command to get more detailed diagnostics output. ``` -## How do I update phpMyAdmin? +#### 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: @@ -931,83 +920,84 @@ Being installed as a system package, it can be updated using the command which u sudo dnf upgrade -y ``` -## How do I upgrade MariaDB? +#### How do I upgrade MariaDB? Initially, MariaDB was at version 11.4 LTS. In case you want to upgrade to a different version, for instance [11.8 LTS](https://mariadb.org/11-8-is-lts/), use the below steps: -* Open the MariaDB.repo file in any text editor. +Open the MariaDB.repo file in any text editor: ```shell sudo nano /etc/yum.repos.d/MariaDB.repo ``` -* Modify the **baseurl** variable to match the desired version, for instance `11.8` instead of `11.4`. -* Clean dnf cache +Modify the **baseurl** variable to match the desired version, for instance `11.8` instead of `11.4`. + +Clean dnf cache: ```shell sudo dnf clean all ``` -* Stop MariaDB +Stop MariaDB: ```shell sudo systemctl stop mariadb ``` -* Upgrade MariaDB +Upgrade MariaDB: ```shell sudo dnf update -y ``` -* Start MariaDB +Start MariaDB: ```shell sudo systemctl start mariadb ``` -* Upgrade databases +Upgrade databases: ```shell sudo mariadb-upgrade -uroot -p ``` -* Restart MariaDB +Restart MariaDB: ```shell sudo systemctl restart mariadb ``` -## How do I delete a virtualhost? +#### How do I delete a virtualhost? If for whatever reason you want to delete a virtualhost, for instance `to-be-deleted.localhost` you need to do the following: -* Delete the folder where the files are located +Delete the folder where the files are located: ```shell sudo rm -rf /var/www/to-be-deleted.localhost ``` -* Delete the Apache configuration file +Delete the Apache configuration file: ```shell sudo rm -f /etc/httpd/sites-available/to-be-deleted.localhost.conf ``` -* Delete the enabled site symlink +Delete the enabled site symlink: ```shell sudo rm -f /etc/httpd/sites-enabled/to-be-deleted.localhost.conf ``` -* Restart httpd server +Restart httpd server: ```shell sudo systemctl restart httpd ``` -## How do I create command aliases? +#### How do I create command aliases? From either your terminal or file explorer, navigate to your home directory (`/home//`). @@ -1024,7 +1014,7 @@ 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 +Example: ```text alias list_files="ls -Al" @@ -1037,5 +1027,3 @@ Then, you can execute your custom alias in a terminal just as a regular command: ```shell list_files ``` - - diff --git a/public/llms-content/running.md b/public/llms-content/running.md index 6fc42ad..27d4c81 100644 --- a/public/llms-content/running.md +++ b/public/llms-content/running.md @@ -1,56 +1,18 @@ -# Running AlmaLinux 10 on WSL 2 - -## Summary - -Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. - -If you are not using WSL 2, connect via SSH with [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/). - -Open `Windows Terminal`. - -Start **AlmaLinux 10** by executing: - -```shell -wsl -d AlmaLinux-10 -``` - -OR - -Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-10`. -This will open a new tab connected to **AlmaLinux 10**. - -To run your applications using WSL 2, you always need to be connected to your **AlmaLinux 10** distribution. -For this, all you need to do is to launch it from a terminal, file explorer or an IDE. -Once launched, you can close the tool you launched it from. -It will stay connected until you shut it down manually or reboot your computer. - -## Check if AlmaLinux 10 is running - -From Windows Terminal, execute: +--- +title: Running AlmaLinux 10 on WSL 2 +description: Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/running" +category: "Development" +language: "en" +--- -```shell -wsl -l -v -``` - -Look for the `AlmaLinux-10` row — its **STATE** column reads **Running** if it's currently active, or **Stopped** otherwise. - -## Shut down AlmaLinux 10 - -To stop just the AlmaLinux 10 distro, leaving any other distros untouched: - -```shell -wsl -t AlmaLinux-10 -``` - -To shut down all currently running WSL 2 distros at once: - -```shell -wsl --shutdown -``` +# Running AlmaLinux 10 on WSL 2 -## Next step +## TL;DR -Continue to [Virtualhosts](virtualhosts/overview.md) to start hosting your projects. +Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal with `wsl -d AlmaLinux-10` or the tab selector dropdown, check whether it's currently running with `wsl -l -v`, and shut it down with `wsl -t AlmaLinux-10` (or `wsl --shutdown` for all distros) when you're done. ## FAQ diff --git a/public/llms-content/setup/installation.md b/public/llms-content/setup/installation.md index 8e557fe..646dc6a 100644 --- a/public/llms-content/setup/installation.md +++ b/public/llms-content/setup/installation.md @@ -1,157 +1,18 @@ -# Install AlmaLinux 10 on WSL 2 - -## Summary - -Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. - -If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). - -This is step 2 of 3: [System Requirements](system-requirements.md) → **Install AlmaLinux 10** (this page) → [Setup Packages](setup-packages.md). - -All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. - -Before proceeding with the installation, we need to make sure that no other WSL 2 distribution (aka: _distro_) is running. -This is important because this installation will fail if required ports are already in use by another distro. - -The distro is downloaded over the internet, so make sure you have a stable connection. -Depending on your connection speed, the download can take anywhere from a couple of minutes to significantly longer. - -Open `Windows Terminal`. - -## Stop other WSL 2 distros - -List all installed distros: - -```shell -wsl -l -v -``` - -If there is no other distro installed, you will see the below output (an empty list): - -```text - NAME STATE VERSION -``` - -In this case, you can jump to the [installation](#install-almalinux-10) section. - -If you have other distros installed, the output could look similar to the below: - -```text - NAME STATE VERSION - 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 it first by executing the below command, after replacing `` with the name of the distro you want to stop: - -```shell -wsl -t -``` - -Once you have stopped all distros, you can continue to the [installation](#install-almalinux-10) section. - -## Install AlmaLinux 10 - -List the available Linux distros by executing: +--- +title: Install AlmaLinux 10 on WSL 2 +description: Learn how to install AlmaLinux 10 on WSL 2 - stop any other running distros, run wsl --install -d AlmaLinux-10, and create your initial Unix user account. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/setup/installation" +category: "Development" +language: "en" +--- -```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`. - -If you try to install a distro that is already installed, the installation process will fail: - -```text -Downloading: AlmaLinux OS 10 -Installing: AlmaLinux OS 10 -A distribution with the supplied name already exists. Use --name to choose a different name. -Error code: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS -``` - -Install the **AlmaLinux 10** 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 **AlmaLinux 10**, 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 or 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 -[@ ]$ -``` - -At this point your terminal has dropped you inside the **AlmaLinux 10** shell (notice the prompt changed). -Keep this window open and continue directly with [Setup Packages](setup-packages.md). -Its commands run inside AlmaLinux 10, not in Windows Terminal. -If you close this window, see [Running on WSL 2](../running.md) to reconnect. +# Install AlmaLinux 10 on WSL 2 -## Next step +## TL;DR -Continue to [Setup Packages](setup-packages.md) to install the required system packages and provision your development environment. +Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. All commands run in `Windows Terminal` on the Windows host, not inside AlmaLinux 10. This is step 2 of 3, after [System Requirements](system-requirements.md) and before [Setup Packages](setup-packages.md). ## FAQ diff --git a/public/llms-content/setup/setup-packages.md b/public/llms-content/setup/setup-packages.md index 784defd..052f0ed 100644 --- a/public/llms-content/setup/setup-packages.md +++ b/public/llms-content/setup/setup-packages.md @@ -1,121 +1,18 @@ -# AlmaLinux 10 Setup - -## Summary - -Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. - -The instructions below also work without using WSL. - -This is step 3 of 3: [System Requirements](system-requirements.md) → [Install AlmaLinux 10](installation.md) → **Setup Packages** (this page). - -All commands on this page are executed **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. -This is the same session left open at the end of the [installation](installation.md) step. -If you closed it, see [Running on WSL 2](../running.md) to reconnect first. - -Update/Upgrade system packages: - -```shell -sudo dnf upgrade -y -``` - -This step downloads packages over the internet and can take a few minutes depending on your connection speed and how many updates are pending. - -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 **AlmaLinux 10** password and hit `Enter`. - -Install system packages: - -```shell -sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y -``` - -`$(rpm -E %almalinux)` resolves to your AlmaLinux major version (`10`), so this installs the matching Remi repository release package. -`dnf` verifies the package's GPG signature before installing it, same as any other package. - -Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections: - -```shell -sudo dnf install ansible-core -y -``` - -```shell -ansible-galaxy collection install community.general community.mysql -``` - -Both of the above require internet access to download packages/collections from their respective repositories (dnf repos and Ansible Galaxy). -If either command fails or times out, check your network connection first. +--- +title: AlmaLinux 10 Setup +description: Update system packages, install Ansible and required repositories, clone this repository, configure config.yml, and run the install.yml Ansible playbook to provision the full development environment. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/setup/setup-packages" +category: "Development" +language: "en" +--- -Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** 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: - -* `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10. -* `config.mariadb.root_password`: the password to set for MariaDB's `root` user (you'll use this to log into phpMyAdmin later). -* `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed. -* `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is. - -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 **AlmaLinux 10** 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: - -If you are not using WSL 2, test the below using your server's IP address instead of `localhost`. - -* [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 **AlmaLinux 10** development environment is ready to use. - -If you are using WSL 2, 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 **AlmaLinux 10**. +# AlmaLinux 10 Setup -## Next step +## TL;DR -Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project. +Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. All commands on this page run **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. This is step 3 of 3, after [System Requirements](system-requirements.md) and [Install AlmaLinux 10](installation.md), and it also works without WSL. ## FAQ diff --git a/public/llms-content/setup/system-requirements.md b/public/llms-content/setup/system-requirements.md index 63024ec..f0d8a78 100644 --- a/public/llms-content/setup/system-requirements.md +++ b/public/llms-content/setup/system-requirements.md @@ -1,73 +1,18 @@ -# System Requirements for AlmaLinux 10 on WSL 2 - -## Summary - -Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. - -If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). - -This is step 1 of 3 in setting up your development environment: **System Requirements** (this page) → [Install AlmaLinux 10](installation.md) → [Setup Packages](setup-packages.md). - -All commands on this page are executed in `Windows Terminal`, on your Windows host, not inside AlmaLinux 10. - -## Minimum requirements - -Before installing WSL 2, make sure your machine meets the following: - -* Windows 10 version 1903 (build 18362) or higher, or Windows 11. -* A 64-bit processor with Second Level Address Translation (SLAT) support. -* Hardware virtualization enabled in your system's BIOS/UEFI (sometimes called `Intel VT-x`, `AMD-V`, or `SVM Mode`). -* At least 4 GB of RAM (8 GB or more recommended for running a full development stack comfortably). -* A few GB of free disk space for the distro plus additional space for your projects and databases. - -For the full, up-to-date list, see Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). - -## Check your WSL version - -Open `Windows Terminal` and execute the following command: - -```shell -wsl -v -``` +--- +title: System Requirements for AlmaLinux 10 on WSL 2 +description: Check whether WSL 2 is already installed, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux), and set WSL 2 as the default version. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/setup/system-requirements" +category: "Development" +language: "en" +--- -The output should look similar to this (your version numbers will likely differ): - -```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 WSL 2 and can proceed to [install AlmaLinux 10](installation.md). -If it doesn't (for example, it shows `WSL version: 1.x.x.x`, or the command isn't recognized), continue with the section below. - -## Install WSL 2 - -Once you've confirmed your machine meets the [minimum requirements](#minimum-requirements) above, 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: +# System Requirements for AlmaLinux 10 on WSL 2 -```shell -wsl --set-default-version 2 -``` +## TL;DR -Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` (in the same format shown [above](#check-your-wsl-version)), which means that your system is ready for using WSL 2 and you can proceed to [install AlmaLinux 10](installation.md). +Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. All commands run in `Windows Terminal` on the Windows host, not inside AlmaLinux 10. This is step 1 of 3, before [Install AlmaLinux 10](installation.md) and [Setup Packages](setup-packages.md). ## FAQ diff --git a/public/llms-content/terminal.md b/public/llms-content/terminal.md index 2250ff6..077b787 100644 --- a/public/llms-content/terminal.md +++ b/public/llms-content/terminal.md @@ -1,16 +1,17 @@ -# Terminal - -## Summary - -Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. +--- +title: Terminal +description: Install Windows Terminal, the tool used throughout the AlmaLinux 10 on WSL 2 guide to run commands and open dedicated tabs for your distro. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/terminal" +category: "Development" +language: "en" +--- -If you are not using WSL, you can jump straight to the [AlmaLinux 10 Setup page](https://docs.dotkernel.org/development/v2/setup/setup-packages/). - -If you're not already using it, we recommend installing [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. +# Terminal -Once your AlmaLinux 10 distro is installed, it gets its own dedicated tab profile in Windows Terminal (see [Running on WSL 2](running.md)), so every command in this guide (Windows and Linux alike) can be run from the same app. +## TL;DR -## Next step +Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. Once the distro is installed, it gets its own dedicated tab profile, so every command in the guide (Windows and Linux alike) can be run from the same app. -Continue to [System Requirements](setup/system-requirements.md) to check whether your machine is ready for WSL 2. +## FAQ diff --git a/public/llms-content/virtualhosts/create-virtualhost.md b/public/llms-content/virtualhosts/create-virtualhost.md index d87bcac..841e8ae 100644 --- a/public/llms-content/virtualhosts/create-virtualhost.md +++ b/public/llms-content/virtualhosts/create-virtualhost.md @@ -1,62 +1,18 @@ -# AlmaLinux 10 Create virtualhosts - -## Summary - -Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. - -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. - -This assumes you've already completed [Setup Packages](../setup/setup-packages.md). -Apache must already be installed before virtualhosts can be created. - -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. - -Virtualhost names should be valid hostnames (lowercase letters, numbers, and hyphens) ending in `.localhost`, for example `api.dotkernel.localhost`. -Avoid spaces or other special characters. +--- +title: AlmaLinux 10 Create virtualhosts +description: Add domains to config.yml and run the create-virtualhost.yml Ansible playbook to provision new virtualhosts on AlmaLinux 10. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/virtualhosts/create-virtualhost" +category: "Development" +language: "en" +--- -You can come back and add more virtualhosts at any time: add new lines under `virtualhosts` and re-run the playbook. -Existing virtualhosts are left untouched. - -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 **AlmaLinux 10** password, iterate over the list of configured, 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`. - -A freshly created virtualhost only has an empty `html` directory - `html/public` doesn't exist yet. -Visiting the virtualhost's URL in your browser will show an error until you place a project there, this is expected. - -Apache logs for each virtualhost are stored separately, for example `/var/www/example.localhost/log/error.log` and `/var/www/example.localhost/log/requests.log`. -Check these first if something isn't working as expected. +# AlmaLinux 10 Create virtualhosts -## Good to know +## TL;DR -* To run your installed projects, you need to start **AlmaLinux 10** 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). +Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. This assumes [Setup Packages](../setup/setup-packages.md) is already complete, since Apache must already be installed before virtualhosts can be created. Using the `*.localhost` pattern means no changes to the Windows `hosts` file are needed. ## FAQ diff --git a/public/llms-content/virtualhosts/overview.md b/public/llms-content/virtualhosts/overview.md index af6c5c1..8078b98 100644 --- a/public/llms-content/virtualhosts/overview.md +++ b/public/llms-content/virtualhosts/overview.md @@ -1,30 +1,18 @@ -# AlmaLinux 10 Overview - -## Summary - -Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. - -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. +--- +title: AlmaLinux 10 Overview +description: Virtualhosts let you host multiple local applications under *.localhost subdomains, routed automatically through Apache without editing the Windows hosts file. +author: "admin" +date_published: "2026-07-27" +canonical_url: "https://docs.dotkernel.org/development/v2/virtualhosts/overview" +category: "Development" +language: "en" +--- -**Example**: - -* `api.dotkernel.localhost`: this could be the endpoint where you host your website's 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 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. +# AlmaLinux 10 Overview -## Next step +## TL;DR -Ready to set one up? -Continue to [Create virtualhost](create-virtualhost.md). +Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. For example, `api.dotkernel.localhost` and `frontend.dotkernel.localhost` can host an API and its consuming frontend side by side on the same machine. ## FAQ From e2ecb66eb4487f3df6b8797cbce3f0108f4c575a Mon Sep 17 00:00:00 2001 From: bidi Date: Tue, 28 Jul 2026 23:32:58 +0300 Subject: [PATCH 5/6] update llms content --- .../llms-content => docs/book}/llms-full.txt | 0 public/llms-content/faq.md | 314 ------------------ public/llms-content/running.md | 42 --- public/llms-content/setup/installation.md | 74 ----- public/llms-content/setup/setup-packages.md | 57 ---- .../llms-content/setup/system-requirements.md | 40 --- public/llms-content/terminal.md | 17 - .../virtualhosts/create-virtualhost.md | 54 --- public/llms-content/virtualhosts/overview.md | 35 -- 9 files changed, 633 deletions(-) rename {public/llms-content => docs/book}/llms-full.txt (100%) delete mode 100644 public/llms-content/faq.md delete mode 100644 public/llms-content/running.md delete mode 100644 public/llms-content/setup/installation.md delete mode 100644 public/llms-content/setup/setup-packages.md delete mode 100644 public/llms-content/setup/system-requirements.md delete mode 100644 public/llms-content/terminal.md delete mode 100644 public/llms-content/virtualhosts/create-virtualhost.md delete mode 100644 public/llms-content/virtualhosts/overview.md diff --git a/public/llms-content/llms-full.txt b/docs/book/llms-full.txt similarity index 100% rename from public/llms-content/llms-full.txt rename to docs/book/llms-full.txt diff --git a/public/llms-content/faq.md b/public/llms-content/faq.md deleted file mode 100644 index bca3b25..0000000 --- a/public/llms-content/faq.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: AlmaLinux 10 Frequently asked questions -description: Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your AlmaLinux 10 development environment. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/faq" -category: "Development" -language: "en" ---- - -# AlmaLinux 10 Frequently asked questions - -## TL;DR - -Quick answers to common questions about switching PHP/Node.js versions, fixing permissions, finding logs, and maintaining your development environment. - -## FAQ - -### 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.5`, `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 -* `php85`: switch to PHP 8.5 - -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: - -```terminaloutput -PHP 8.4.8 (cli) (built: Jun 3 2025 16:29:26) (NTS gcc x86_64) -Copyright (c) The PHP Group -Built by Remi's RPM repository #StandWithUkraine -Zend Engine v4.4.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: - -* `node24`: switch to Node.js 24 -* `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 -``` - -Depending on the selected Node.js version, the output should look similar to the below: - -```terminaloutput -v24.13.0 -``` - -Check npm version: - -```shell -npm -v -``` - -Depending on the current npm version, the output should look similar to the below: - -```terminaloutput -11.9.0 -``` - -### How do I fix common permission issues? - -If running your project, you encounter permission issues, follow the below steps. - -`chmod -R 777` grants read/write/execute access to everyone, which is only appropriate for a local development environment like this one. -Avoid carrying this habit into staging or production, where permissions should be scoped more narrowly (for example, to the web server's user/group). - -#### 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.9.0 (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.9.0 2025-11-13 10:37:16 -PHP version 8.5.0 (/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 upgrade MariaDB? - -Initially, MariaDB was at version 11.4 LTS. -In case you want to upgrade to a different version, for instance [11.8 LTS](https://mariadb.org/11-8-is-lts/), use the below steps: - -* Open the MariaDB.repo file in any text editor. - -```shell -sudo nano /etc/yum.repos.d/MariaDB.repo -``` - -* Modify the **baseurl** variable to match the desired version, for instance `11.8` instead of `11.4`. -* Clean dnf cache - -```shell -sudo dnf clean all -``` - -* Stop MariaDB - -```shell -sudo systemctl stop mariadb -``` - -* Upgrade MariaDB - -```shell -sudo dnf update -y -``` - -* Start MariaDB - -```shell -sudo systemctl start mariadb -``` - -* Upgrade databases - -```shell -sudo mariadb-upgrade -uroot -p -``` - -* Restart MariaDB - -```shell -sudo systemctl restart mariadb -``` - -### How do I delete a virtualhost? - -If for whatever reason you want to delete a virtualhost, for instance `to-be-deleted.localhost` you need to do the following: - -* Delete the folder where the files are located - -```shell -sudo rm -rf /var/www/to-be-deleted.localhost -``` - -* Delete the Apache configuration file - -```shell -sudo rm -f /etc/httpd/sites-available/to-be-deleted.localhost.conf -``` - -* Delete the enabled site symlink - -```shell -sudo rm -f /etc/httpd/sites-enabled/to-be-deleted.localhost.conf -``` - -* Restart httpd server - -```shell -sudo systemctl restart httpd -``` - -### 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, create 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/public/llms-content/running.md b/public/llms-content/running.md deleted file mode 100644 index 27d4c81..0000000 --- a/public/llms-content/running.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Running AlmaLinux 10 on WSL 2 -description: Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal, check whether it's currently running, and shut it down when you're done. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/running" -category: "Development" -language: "en" ---- - -# Running AlmaLinux 10 on WSL 2 - -## TL;DR - -Start (or reconnect to) your AlmaLinux 10 distro from Windows Terminal with `wsl -d AlmaLinux-10` or the tab selector dropdown, check whether it's currently running with `wsl -l -v`, and shut it down with `wsl -t AlmaLinux-10` (or `wsl --shutdown` for all distros) when you're done. - -## FAQ - -### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? - -Confirm it's actually installed by running: - -```shell -wsl -l -v -``` - -If it's missing from the list entirely, revisit [Install AlmaLinux 10](setup/installation.md). -Restarting Windows Terminal after installation also helps it pick up the new tab profile. - -### What if `wsl -d AlmaLinux-10` fails to start? - -Run the below command to confirm the distro is installed and check its current state: - -```shell -wsl -l -v -``` - -If another distro is using the same resources, stop it first with the below command, then retry: - -```shell -wsl -t -``` diff --git a/public/llms-content/setup/installation.md b/public/llms-content/setup/installation.md deleted file mode 100644 index 646dc6a..0000000 --- a/public/llms-content/setup/installation.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Install AlmaLinux 10 on WSL 2 -description: Learn how to install AlmaLinux 10 on WSL 2 - stop any other running distros, run wsl --install -d AlmaLinux-10, and create your initial Unix user account. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/setup/installation" -category: "Development" -language: "en" ---- - -# Install AlmaLinux 10 on WSL 2 - -## TL;DR - -Stop any other running WSL 2 distros, then install the AlmaLinux 10 distro (`wsl --install -d AlmaLinux-10`) and create the initial Unix user account. All commands run in `Windows Terminal` on the Windows host, not inside AlmaLinux 10. This is step 2 of 3, after [System Requirements](system-requirements.md) and before [Setup Packages](setup-packages.md). - -## FAQ - -### What if the installation fails because a distro is already running? - -Make sure no other WSL 2 distro is running by checking: - -```shell -wsl -l -v -``` - -All distros must show **Stopped**. Stop any running distro with the below command before retrying the installation: - -```shell -wsl -t -``` - -### What if `AlmaLinux-10` is already installed? - -The installation will fail with `A distribution with the supplied name already exists`. -Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. - -### Does the username need to match my Windows username? - -No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. - -### What if I get a `BAD PASSWORD` message? - -This is just a strength warning. -Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. - -### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? - -Run the below command to see the current list of installable distros and their **NAME** values: - -```shell -wsl --list --online -``` - -### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? - -This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. -Revisit the [System Requirements](system-requirements.md) page and confirm both. -A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. - -### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? - -You don't need the Store for this step. -`wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. - -### How do I completely remove AlmaLinux-10 and start over? - -Unregister the distro, which deletes it and all its data, then reinstall it from scratch: - -```shell -wsl --unregister AlmaLinux-10 -``` - -Once unregistered, you can run `wsl --install -d AlmaLinux-10` again as described above. diff --git a/public/llms-content/setup/setup-packages.md b/public/llms-content/setup/setup-packages.md deleted file mode 100644 index 052f0ed..0000000 --- a/public/llms-content/setup/setup-packages.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: AlmaLinux 10 Setup -description: Update system packages, install Ansible and required repositories, clone this repository, configure config.yml, and run the install.yml Ansible playbook to provision the full development environment. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/setup/setup-packages" -category: "Development" -language: "en" ---- - -# AlmaLinux 10 Setup - -## TL;DR - -Update system packages, install Ansible and required repositories, clone this repository, configure `config.yml`, and run the `install.yml` Ansible playbook to provision the full development environment. All commands on this page run **inside the AlmaLinux 10 shell** (Linux), not in Windows Terminal. This is step 3 of 3, after [System Requirements](system-requirements.md) and [Install AlmaLinux 10](installation.md), and it also works without WSL. - -## FAQ - -### What if `config.yml` doesn't exist yet? - -Duplicate the provided template by running: - -```shell -cp config.yml.dist config.yml -``` - -Then fill in the empty fields before running the playbook. - -### What if the Ansible playbook fails partway through? - -Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: - -```shell -ansible-playbook -i hosts install.yml --ask-become-pass -``` - -It is safe to re-run. - -### What if `ansible-galaxy collection install` fails or times out? - -This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. -Check your connection and re-run the command. -It's safe to run again even if some collections already installed successfully. - -### What if `http://localhost/` doesn't load after installation? - -If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. -Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. - -### How do I log into phpMyAdmin? - -Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. - -### Can I run this setup without WSL? - -Yes, the instructions work the same way on a non-WSL AlmaLinux system. -You can then skip the WSL-specific notes. diff --git a/public/llms-content/setup/system-requirements.md b/public/llms-content/setup/system-requirements.md deleted file mode 100644 index f0d8a78..0000000 --- a/public/llms-content/setup/system-requirements.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: System Requirements for AlmaLinux 10 on WSL 2 -description: Check whether WSL 2 is already installed, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux), and set WSL 2 as the default version. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/setup/system-requirements" -category: "Development" -language: "en" ---- - -# System Requirements for AlmaLinux 10 on WSL 2 - -## TL;DR - -Check whether WSL 2 is already installed and, if not, enable the required Windows features (Hyper-V, Virtual Machine Platform, Windows Subsystem for Linux) and set WSL 2 as the default version. All commands run in `Windows Terminal` on the Windows host, not inside AlmaLinux 10. This is step 1 of 3, before [Install AlmaLinux 10](installation.md) and [Setup Packages](setup-packages.md). - -## FAQ - -### What if `wsl -v` shows WSL version 1 instead of 2? - -Run: - -```shell -wsl --set-default-version 2 -``` - -Then re-run `wsl -v` to confirm the version has switched. - -### What if the `OptionalFeatures` dialog doesn't show all required features? - -Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. - -### Do I need to restart my computer after enabling the Windows features? - -Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. - -### What if my machine doesn't meet the minimum requirements for WSL 2? - -Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. -If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). diff --git a/public/llms-content/terminal.md b/public/llms-content/terminal.md deleted file mode 100644 index 077b787..0000000 --- a/public/llms-content/terminal.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Terminal -description: Install Windows Terminal, the tool used throughout the AlmaLinux 10 on WSL 2 guide to run commands and open dedicated tabs for your distro. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/terminal" -category: "Development" -language: "en" ---- - -# Terminal - -## TL;DR - -Install Windows Terminal, the tool you'll use throughout this guide to run WSL 2 commands and to open dedicated tabs for your AlmaLinux 10 distro. Once the distro is installed, it gets its own dedicated tab profile, so every command in the guide (Windows and Linux alike) can be run from the same app. - -## FAQ diff --git a/public/llms-content/virtualhosts/create-virtualhost.md b/public/llms-content/virtualhosts/create-virtualhost.md deleted file mode 100644 index 841e8ae..0000000 --- a/public/llms-content/virtualhosts/create-virtualhost.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: AlmaLinux 10 Create virtualhosts -description: Add domains to config.yml and run the create-virtualhost.yml Ansible playbook to provision new virtualhosts on AlmaLinux 10. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/virtualhosts/create-virtualhost" -category: "Development" -language: "en" ---- - -# AlmaLinux 10 Create virtualhosts - -## TL;DR - -Add your desired domains to `config.yml` and run the `create-virtualhost.yml` Ansible playbook to provision each one. This assumes [Setup Packages](../setup/setup-packages.md) is already complete, since Apache must already be installed before virtualhosts can be created. Using the `*.localhost` pattern means no changes to the Windows `hosts` file are needed. - -## FAQ - -### What if I don't have a `config.yml` file yet? - -Duplicate the provided template by running the below command inside `development/wsl`: - -```shell -cp config.yml.dist config.yml -``` - -Then add your virtualhosts under the `virtualhosts` key. - -### What happens if I list a virtualhost that already exists? - -It will simply be skipped. -Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from `config.yml`. - -### Where should I put my project's files? - -Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. -The document root is set to the `public` subdirectory of that location, for example `/var/www/example.localhost/html/public`. - -### How do I make the DocumentRoot point directly to `html` instead of `html/public`? - -Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. - -### How do I access my virtualhost if AlmaLinux 10 isn't running? - -You need to start **AlmaLinux 10** first. -Your virtualhosts are only reachable while the distro is running. - -### What if I hit permission errors when writing to my project's files? - -See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. - -### How do I delete a virtualhost I no longer need? - -See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. diff --git a/public/llms-content/virtualhosts/overview.md b/public/llms-content/virtualhosts/overview.md deleted file mode 100644 index 8078b98..0000000 --- a/public/llms-content/virtualhosts/overview.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: AlmaLinux 10 Overview -description: Virtualhosts let you host multiple local applications under *.localhost subdomains, routed automatically through Apache without editing the Windows hosts file. -author: "admin" -date_published: "2026-07-27" -canonical_url: "https://docs.dotkernel.org/development/v2/virtualhosts/overview" -category: "Development" -language: "en" ---- - -# AlmaLinux 10 Overview - -## TL;DR - -Virtualhosts let you host multiple local applications under `*.localhost` subdomains, routed automatically through Apache without editing the Windows `hosts` file. For example, `api.dotkernel.localhost` and `frontend.dotkernel.localhost` can host an API and its consuming frontend side by side on the same machine. - -## FAQ - -### Do I need to edit the Windows `hosts` file for my virtualhosts? - -No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. - -### Can I use a domain that doesn't end in `.localhost`? - -The automatic routing described here relies on the `*.localhost` pattern. -Using a different TLD would require manually editing the Windows `hosts` file yourself. - -### How are the subdomain and domain parts of a virtualhost URL structured? - -The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. - -### Where do I actually create a virtualhost? - -This page only covers the concept. -See [Create virtualhost](create-virtualhost.md) for the steps to provision one. From f0326bc56b3a8f8db946eb61110548ebb4e8f9e8 Mon Sep 17 00:00:00 2001 From: bidi Date: Wed, 29 Jul 2026 15:08:51 +0300 Subject: [PATCH 6/6] updated faq formatting --- docs/book/v2/running.md | 8 ++--- docs/book/v2/setup/installation.md | 32 +++++++++---------- docs/book/v2/setup/setup-packages.md | 24 +++++++------- docs/book/v2/setup/system-requirements.md | 16 +++++----- .../v2/virtualhosts/create-virtualhost.md | 28 ++++++++-------- docs/book/v2/virtualhosts/overview.md | 16 +++++----- 6 files changed, 62 insertions(+), 62 deletions(-) diff --git a/docs/book/v2/running.md b/docs/book/v2/running.md index 8d690ce..09a70c3 100644 --- a/docs/book/v2/running.md +++ b/docs/book/v2/running.md @@ -54,9 +54,9 @@ Continue to [Virtualhosts](virtualhosts/overview.md) to start hosting your proje ## FAQ -### What if `AlmaLinux-10` doesn't appear in the tab selector dropdown? +**Q: What if `AlmaLinux-10` doesn't appear in the tab selector dropdown?** -Confirm it's actually installed by running: +A: Confirm it's actually installed by running: ```shell wsl -l -v @@ -65,9 +65,9 @@ wsl -l -v If it's missing from the list entirely, revisit [Install AlmaLinux 10](setup/installation.md). Restarting Windows Terminal after installation also helps it pick up the new tab profile. -### What if `wsl -d AlmaLinux-10` fails to start? +**Q: What if `wsl -d AlmaLinux-10` fails to start?** -Run the below command to confirm the distro is installed and check its current state: +A: Run the below command to confirm the distro is installed and check its current state: ```shell wsl -l -v diff --git a/docs/book/v2/setup/installation.md b/docs/book/v2/setup/installation.md index e7097be..fe7a4f8 100644 --- a/docs/book/v2/setup/installation.md +++ b/docs/book/v2/setup/installation.md @@ -155,9 +155,9 @@ Continue to [Setup Packages](setup-packages.md) to install the required system p ## FAQ -### What if the installation fails because a distro is already running? +**Q: What if the installation fails because a distro is already running?** -Make sure no other WSL 2 distro is running by checking: +A: Make sure no other WSL 2 distro is running by checking: ```shell wsl -l -v @@ -169,42 +169,42 @@ All distros must show **Stopped**. Stop any running distro with the below comman wsl -t ``` -### What if `AlmaLinux-10` is already installed? +**Q: What if `AlmaLinux-10` is already installed?** -The installation will fail with `A distribution with the supplied name already exists`. +A: The installation will fail with `A distribution with the supplied name already exists`. Use a different `--name` value, or remove the existing distro first if you intend to reinstall it. -### Does the username need to match my Windows username? +**Q: Does the username need to match my Windows username?** -No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. +A: No, the Unix username created during installation can be any alphanumeric string and does not need to match your Windows username. -### What if I get a `BAD PASSWORD` message? +**Q: What if I get a `BAD PASSWORD` message?** -This is just a strength warning. +A: This is just a strength warning. Press `Enter` to choose a different password, or continue retyping the same one if you want to keep it. -### Where can I find the list of available distros if `AlmaLinux-10` isn't shown? +**Q: Where can I find the list of available distros if `AlmaLinux-10` isn't shown?** -Run the below command to see the current list of installable distros and their **NAME** values: +A: Run the below command to see the current list of installable distros and their **NAME** values: ```shell wsl --list --online ``` -### What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error? +**Q: What if `wsl --install -d AlmaLinux-10` fails or hangs with no clear error?** -This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. +A: This is most often caused by hardware virtualization being disabled in your BIOS/UEFI, or by Hyper-V/Virtual Machine Platform not being enabled. Revisit the [System Requirements](system-requirements.md) page and confirm both. A blocked or unstable internet connection (including corporate proxies/firewalls) can also cause the download to stall. -### What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)? +**Q: What if the Microsoft Store is unavailable or blocked (for example, on a work laptop)?** -You don't need the Store for this step. +A: You don't need the Store for this step. `wsl --install -d AlmaLinux-10` downloads and registers the distro directly, without going through the Store. -### How do I completely remove AlmaLinux-10 and start over? +**Q: How do I completely remove AlmaLinux-10 and start over?** -Unregister the distro, which deletes it and all its data, then reinstall it from scratch: +A: Unregister the distro, which deletes it and all its data, then reinstall it from scratch: ```shell wsl --unregister AlmaLinux-10 diff --git a/docs/book/v2/setup/setup-packages.md b/docs/book/v2/setup/setup-packages.md index 21ef27b..9748bee 100644 --- a/docs/book/v2/setup/setup-packages.md +++ b/docs/book/v2/setup/setup-packages.md @@ -119,9 +119,9 @@ Your environment is now provisioned. Continue to [Running on WSL 2](../running.m ## FAQ -### What if `config.yml` doesn't exist yet? +**Q: What if `config.yml` doesn't exist yet?** -Duplicate the provided template by running: +A: Duplicate the provided template by running: ```shell cp config.yml.dist config.yml @@ -129,9 +129,9 @@ cp config.yml.dist config.yml Then fill in the empty fields before running the playbook. -### What if the Ansible playbook fails partway through? +**Q: What if the Ansible playbook fails partway through?** -Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: +A: Review the summary output for the failed task, fix the underlying issue (for example, a misconfigured field in `config.yml`), and re-run: ```shell ansible-playbook -i hosts install.yml --ask-become-pass @@ -139,22 +139,22 @@ ansible-playbook -i hosts install.yml --ask-become-pass It is safe to re-run. -### What if `ansible-galaxy collection install` fails or times out? +**Q: What if `ansible-galaxy collection install` fails or times out?** -This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. +A: This command downloads collections from Ansible Galaxy over the internet, so it fails if your network connection is down, unstable, or blocked by a proxy/firewall. Check your connection and re-run the command. It's safe to run again even if some collections already installed successfully. -### What if `http://localhost/` doesn't load after installation? +**Q: What if `http://localhost/` doesn't load after installation?** -If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. +A: If you are not using WSL 2, make sure you are using your server's IP address instead of `localhost`. Otherwise, confirm the playbook completed without errors and that your **AlmaLinux 10** distro is still running. -### How do I log into phpMyAdmin? +**Q: How do I log into phpMyAdmin?** -Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. +A: Use the username `root` and the password you configured under `mariadb` -> `root_password` in `config.yml`. -### Can I run this setup without WSL? +**Q: Can I run this setup without WSL?** -Yes, the instructions work the same way on a non-WSL AlmaLinux system. +A: Yes, the instructions work the same way on a non-WSL AlmaLinux system. You can then skip the WSL-specific notes. diff --git a/docs/book/v2/setup/system-requirements.md b/docs/book/v2/setup/system-requirements.md index 3a6fa03..d208c7b 100644 --- a/docs/book/v2/setup/system-requirements.md +++ b/docs/book/v2/setup/system-requirements.md @@ -71,9 +71,9 @@ Run `wsl -v` again - this time the output should display `WSL version: 2.x.x.x` ## FAQ -### What if `wsl -v` shows WSL version 1 instead of 2? +**Q: What if `wsl -v` shows WSL version 1 instead of 2?** -Run: +A: Run: ```shell wsl --set-default-version 2 @@ -81,15 +81,15 @@ wsl --set-default-version 2 Then re-run `wsl -v` to confirm the version has switched. -### What if the `OptionalFeatures` dialog doesn't show all required features? +**Q: What if the `OptionalFeatures` dialog doesn't show all required features?** -Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. +A: Install them manually first using Microsoft's [manual install guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual), then continue with the steps above. -### Do I need to restart my computer after enabling the Windows features? +**Q: Do I need to restart my computer after enabling the Windows features?** -Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. +A: Yes, a restart is required after clicking `Ok` in the `OptionalFeatures` dialog for the feature changes to take effect. -### What if my machine doesn't meet the minimum requirements for WSL 2? +**Q: What if my machine doesn't meet the minimum requirements for WSL 2?** -Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. +A: Double-check the [minimum requirements](#minimum-requirements) above, in particular that hardware virtualization is enabled in your BIOS/UEFI - this is the most common blocker. If you're still unsure, consult Microsoft's [prerequisites documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites). diff --git a/docs/book/v2/virtualhosts/create-virtualhost.md b/docs/book/v2/virtualhosts/create-virtualhost.md index 7f00ef2..fd461f5 100644 --- a/docs/book/v2/virtualhosts/create-virtualhost.md +++ b/docs/book/v2/virtualhosts/create-virtualhost.md @@ -60,9 +60,9 @@ You will install your project under the `html` directory of your project, for ex ## FAQ -### What if I don't have a `config.yml` file yet? +**Q: What if I don't have a `config.yml` file yet?** -Duplicate the provided template by running the below command inside `development/wsl`: +A: Duplicate the provided template by running the below command inside `development/wsl`: ```shell cp config.yml.dist config.yml @@ -70,29 +70,29 @@ cp config.yml.dist config.yml Then add your virtualhosts under the `virtualhosts` key. -### What happens if I list a virtualhost that already exists? +**Q: What happens if I list a virtualhost that already exists?** -It will simply be skipped. +A: It will simply be skipped. Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from `config.yml`. -### Where should I put my project's files? +**Q: Where should I put my project's files?** -Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. +A: Under the `html` directory of your virtualhost, for example `/var/www/example.localhost/html`. The document root is set to the `public` subdirectory of that location, for example `/var/www/example.localhost/html/public`. -### How do I make the DocumentRoot point directly to `html` instead of `html/public`? +**Q: How do I make the DocumentRoot point directly to `html` instead of `html/public`?** -Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. +A: Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost` and change the `DocumentRoot` accordingly. -### How do I access my virtualhost if AlmaLinux 10 isn't running? +**Q: How do I access my virtualhost if AlmaLinux 10 isn't running?** -You need to start **AlmaLinux 10** first. +A: You need to start **AlmaLinux 10** first. Your virtualhosts are only reachable while the distro is running. -### What if I hit permission errors when writing to my project's files? +**Q: What if I hit permission errors when writing to my project's files?** -See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. +A: See the [permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. -### How do I delete a virtualhost I no longer need? +**Q: How do I delete a virtualhost I no longer need?** -See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. +A: See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. diff --git a/docs/book/v2/virtualhosts/overview.md b/docs/book/v2/virtualhosts/overview.md index 1e7f3a4..0e3e7f5 100644 --- a/docs/book/v2/virtualhosts/overview.md +++ b/docs/book/v2/virtualhosts/overview.md @@ -28,20 +28,20 @@ Continue to [Create virtualhost](create-virtualhost.md). ## FAQ -### Do I need to edit the Windows `hosts` file for my virtualhosts? +**Q: Do I need to edit the Windows `hosts` file for my virtualhosts?** -No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. +A: No, as long as you use the `*.localhost` pattern (for example `api.dotkernel.localhost`), these domains are routed automatically and require no `hosts` file changes. -### Can I use a domain that doesn't end in `.localhost`? +**Q: Can I use a domain that doesn't end in `.localhost`?** -The automatic routing described here relies on the `*.localhost` pattern. +A: The automatic routing described here relies on the `*.localhost` pattern. Using a different TLD would require manually editing the Windows `hosts` file yourself. -### How are the subdomain and domain parts of a virtualhost URL structured? +**Q: How are the subdomain and domain parts of a virtualhost URL structured?** -The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. +A: The subdomain identifies the application (for example `api` or `frontend`), and the domain identifies the project (for example `dotkernel`) - together with the `.localhost` TLD, Apache routes the request to the right place. -### Where do I actually create a virtualhost? +**Q: Where do I actually create a virtualhost?** -This page only covers the concept. +A: This page only covers the concept. See [Create virtualhost](create-virtualhost.md) for the steps to provision one.