From 1c6809890e808ed81ff5f29a596c710a157c7d43 Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 24 Sep 2026 18:31:13 +0300 Subject: [PATCH 1/2] Rewrite the landing page and shrink the duplicated wsl/ install guide README.md (also served as docs/book/index.md via symlink - it's the MkDocs "Home" page and the GitHub-facing repo README at once) was stale v1-era content: it duplicated the System Requirements page, had a "WLS2" typo, and linked to wsl/README.md via a path that resolves correctly on GitHub but not inside the built MkDocs site (the two contexts have different relative-path bases, since docs_dir is docs/book). Replaced it with a short landing page: a "what you get" stack overview with a rough setup-time estimate, an explanation of the v1 (AlmaLinux 9) vs v2 (AlmaLinux 10) split, and getting-started links. Because this file is rendered from two different physical locations, its links to the versioned docs use absolute docs.dotkernel.org URLs rather than relative paths, which is the only form that resolves correctly in both contexts. wsl/README.md duplicated the full install walkthrough and had drifted (stale AlmaLinux-9 sample in its distro list, a stray period in the username example, passwd message wording that disagreed with the versioned docs). Shrunk it to a short pointer at the folder's purpose plus a link to the live installation page, so there's one source of truth (docs/book/v2/setup/installation.md) instead of two drifting copies. --- README.md | 67 ++++---------- wsl/README.md | 252 +------------------------------------------------- 2 files changed, 22 insertions(+), 297 deletions(-) diff --git a/README.md b/README.md index 02e9b4d..dfa44eb 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,31 @@ -# WSL2 development environment +# Development environment -This is a collection of Ansible scripts helping with the creation and maintenance of your WSL2 development environment. +This repo provisions a full local development environment for Dotkernel projects using an Ansible playbook, runnable directly on Linux or inside WSL 2 on Windows. -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... +## What you get -## Check if WLS2 is already available +Running the playbook installs and configures: -Open `Windows Terminal` and execute the following command: +* Apache +* PHP-FPM (version pinned in `wsl/roles/php/tasks/main.yml`) +* MariaDB (version pinned in `wsl/roles/mariadb/templates/MariaDB.repo.j2`) +* phpMyAdmin +* Composer +* Node.js 22 -```shell -wsl -v -``` +A full run typically takes somewhere between 15 and 30 minutes, depending on your internet connection - most of that time is spent downloading packages. -The output should look similar to this: +## Which version should I use? -```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 -``` +Two versions of this guide are maintained: -If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux 10](wsl/README.md). +* **v2** targets **AlmaLinux 10** and is the current, actively maintained version - start here unless you have a specific reason not to. +* **v1** targets **AlmaLinux 9**, for environments that haven't moved to AlmaLinux 10 yet. -## Install WSL2 +## Getting started -Before proceeding with the installation, please consult Microsoft's [documentation](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites) regarding the minimum requirements for running WSL2. +Full documentation is published at . -Once you identified that your machine can run WSL2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`. -This will open a window where you can turn Windows features on/off. -Make sure that the below features are activated (checked): +If you're using WSL 2 (Windows Subsystem for Linux) to run your development environment, start with [Terminal](https://docs.dotkernel.org/development/v2/terminal/) to install Windows Terminal, then continue to [System Requirements](https://docs.dotkernel.org/development/v2/setup/system-requirements/). -* `Hyper-V` (including its sub-features) -* `Virtual Machine Platform` -* `Windows Subsystem for Linux` - -> If any of the above features are missing, then first you need to install them manually using [this guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual) and then continue with the below steps. - -Click `Ok` and restart your computer. - -Open Microsoft Store, search for `Windows Subsystem for Linux` and install it. - -Make sure that version **2** of WSL is set as default by executing the below command in Windows Terminal: - -```shell -wsl --set-default-version 2 -``` - -To test, run again the following command: - -```shell -wsl -v -``` - -This time the output should display `WSL version: 2.x.x.x`, which means that your system is ready for using **WSL2** and you can proceed to [install AlmaLinux 10](wsl/README.md). +If you're not using WSL (for example, a native Linux host), you can jump straight to [Setup Packages](https://docs.dotkernel.org/development/v2/setup/setup-packages/). diff --git a/wsl/README.md b/wsl/README.md index ed81777..00f9c77 100644 --- a/wsl/README.md +++ b/wsl/README.md @@ -1,251 +1,5 @@ -# AlmaLinux 10 Installation +# WSL 2 development environment -Before proceeding with the installation, we need to make sure that no other WSL2 distribution (aka: _distro_) is running. -This is important because this installation will fail if required ports are already in use by another distro. +This folder contains the Ansible playbook that provisions a local Dotkernel development environment (Apache, PHP-FPM, MariaDB, phpMyAdmin, Composer, Node.js), runnable directly on Linux or inside WSL 2 on Windows. -Open `Windows Terminal`. - -## Stop other WSL2 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-8 Stopped 2 -* AlmaLinux-9 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. -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—else, continue with retyping your password): - -Next, you are asked to retype your password: - -```text -Retype new password: -``` - -Finally, you should see the following message: - -```text -passwd: all authentication tokens updated successfully. -[@ ]$ -``` - -## Setup AlmaLinux 10 - -Install system packages: - -```shell -sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-10.rpm -y -``` - -You should see the below message, shown the first time you execute a command which requires elevated permissions (hence the `sudo` modifier at the beginning of the command). - -```text -We trust you have received the usual lecture from the local System Administrator. It usually boils down to these three things: - - #1) Respect the privacy of others. - #2) Think before you type. - #3) With great power comes great responsibility. - -For security reasons, the password you type will not be visible. - -[sudo] password for dotkernel: -``` - -Input your **AlmaLinux 10** password and hit `Enter`. - -Update/Upgrade system packages: - -```shell -sudo dnf upgrade -y -``` - -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 -``` - -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. -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: - -* [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. - -> 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**. - -## Create virtualhosts - -> By using the `*.localhost` pattern for any new virtualhost, you do not need to modify the `hosts` file in Windows, because these are routed by default. - -Move inside the directory `development/wsl`: - -```shell -cd ~/development/wsl/ -``` - -If you don't already have a `config.yml` file, duplicate `config.yml.dist` as `config.yml`. - -Using your preferred text editor, open `config.yml` and, under the `virtualhosts` key, enter the virtualhosts that you want to create, each on its own line. -Already existing virtualhosts will be skipped, their contents will not be lost, no need to comment or remove them. -Save and close the file. - -Create the specified virtualhosts: - -```shell -ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass -``` - -This process will ask for your **AlmaLinux 10** password, iterate over the list of configured `virtualhosts` and output a short summary with the results. -Your virtualhost should be accessible and ready to use. - -You will install your project under the `html` directory of your project, for example `/var/www/example.localhost/html`. - -> The virtualhost's document root is set to the `public` directory of the above location, for example `/var/www/example.localhost/html/public`. - -> If you want to have the DocumentRoot directly in `html` folder, you need to modify the file `/etc/httpd/sites-available/example.localhost`. - -### Good to know - -* To run your installed projects, you need to start **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.5 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). +Full, up-to-date installation instructions: From e6ca476d9171a3e86fe314b428ff25641be36fb6 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 25 Sep 2026 13:51:30 +0300 Subject: [PATCH 2/2] updated readme Signed-off-by: bidi --- README.md | 4 +--- wsl/README.md | 3 ++- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index dfa44eb..d09c88a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Development environment -This repo provisions a full local development environment for Dotkernel projects using an Ansible playbook, runnable directly on Linux or inside WSL 2 on Windows. +This repo provisions a full local development environment for any PHP framework or project, using an Ansible playbook, runnable directly on Linux or inside WSL 2 on Windows. ## What you get @@ -13,8 +13,6 @@ Running the playbook installs and configures: * Composer * Node.js 22 -A full run typically takes somewhere between 15 and 30 minutes, depending on your internet connection - most of that time is spent downloading packages. - ## Which version should I use? Two versions of this guide are maintained: diff --git a/wsl/README.md b/wsl/README.md index 00f9c77..14b3fc4 100644 --- a/wsl/README.md +++ b/wsl/README.md @@ -1,5 +1,6 @@ # WSL 2 development environment -This folder contains the Ansible playbook that provisions a local Dotkernel development environment (Apache, PHP-FPM, MariaDB, phpMyAdmin, Composer, Node.js), runnable directly on Linux or inside WSL 2 on Windows. +This folder contains the Ansible playbook used to provision a local development environment (Apache, PHP-FPM, MariaDB, phpMyAdmin, Composer, and Node.js). +It runs directly on Linux or via WSL 2 on Windows, and is designed for development in any PHP framework or project. Full, up-to-date installation instructions: