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 13e911e..e7097be 100644 --- a/docs/book/v2/setup/installation.md +++ b/docs/book/v2/setup/installation.md @@ -1,10 +1,21 @@ # 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 @@ -27,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 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 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 @@ -90,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 @@ -112,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: @@ -126,3 +143,71 @@ 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: + +```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/docs/book/v2/setup/setup-packages.md b/docs/book/v2/setup/setup-packages.md index 8542806..21ef27b 100644 --- a/docs/book/v2/setup/setup-packages.md +++ b/docs/book/v2/setup/setup-packages.md @@ -1,13 +1,25 @@ # 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 +43,9 @@ 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 +56,9 @@ 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 +83,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: @@ -74,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: @@ -86,4 +110,51 @@ 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 + +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/docs/book/v2/setup/system-requirements.md b/docs/book/v2/setup/system-requirements.md index e137459..3a6fa03 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,29 @@ 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). + +## FAQ + +### What if `wsl -v` shows WSL version 1 instead of 2? + +Run: ```shell -wsl -v +wsl --set-default-version 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). +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/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. diff --git a/public/llms-content/faq.md b/public/llms-content/faq.md new file mode 100644 index 0000000..bca3b25 --- /dev/null +++ b/public/llms-content/faq.md @@ -0,0 +1,314 @@ +--- +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/llms-full.txt b/public/llms-content/llms-full.txt new file mode 100644 index 0000000..06579f4 --- /dev/null +++ b/public/llms-content/llms-full.txt @@ -0,0 +1,1029 @@ +# DotKernel Development Environment (AlmaLinux 10 on WSL 2) + +> 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. + +## 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. + +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. + +## Setup + +### 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 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), 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 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 section below. + +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 section below. + +#### 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 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. + +## Guides + +### 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 in the FAQ section below. + +##### 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 + +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: + +```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? + +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: + +```text +v24.13.0 +``` + +Check npm version: + +```shell +npm -v +``` + +Depending on the current npm version, the output should look similar to the below: + +```text +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: `data` directory not writable + +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: `public/uploads` directory not writable + +PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not writable... + +Solution: + +```shell +chmod -R 777 public/uploads +``` + +##### 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: + +```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..27d4c81 --- /dev/null +++ b/public/llms-content/running.md @@ -0,0 +1,42 @@ +--- +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 new file mode 100644 index 0000000..646dc6a --- /dev/null +++ b/public/llms-content/setup/installation.md @@ -0,0 +1,74 @@ +--- +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 new file mode 100644 index 0000000..052f0ed --- /dev/null +++ b/public/llms-content/setup/setup-packages.md @@ -0,0 +1,57 @@ +--- +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 new file mode 100644 index 0000000..f0d8a78 --- /dev/null +++ b/public/llms-content/setup/system-requirements.md @@ -0,0 +1,40 @@ +--- +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 new file mode 100644 index 0000000..077b787 --- /dev/null +++ b/public/llms-content/terminal.md @@ -0,0 +1,17 @@ +--- +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 new file mode 100644 index 0000000..841e8ae --- /dev/null +++ b/public/llms-content/virtualhosts/create-virtualhost.md @@ -0,0 +1,54 @@ +--- +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 new file mode 100644 index 0000000..8078b98 --- /dev/null +++ b/public/llms-content/virtualhosts/overview.md @@ -0,0 +1,35 @@ +--- +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.