@@ -1,60 +1,29 @@
-# 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 any PHP framework or project, 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
-```
+## Which version should I use?
 
-The output should look similar to this:
+Two versions of this guide are maintained:
 
-```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
-```
+* **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.
 
-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).
+## Getting started
 
-## Install WSL2
+Full documentation is published at <https://docs.dotkernel.org/development/v2/>.
 
-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.
+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/).
 
-Once you identified that your machine can run WSL2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
-This will open a window where you can turn Windows features on/off.
-Make sure that the below features are activated (checked):
-
-* `Hyper-V` (including its sub-features)
-* `Virtual Machine Platform`
-* `Windows Subsystem for Linux`
-
-> If any of the above features are missing, then first you need to install them manually using [this guide](https://docs.microsoft.com/en-us/windows/wsl/install-manual) and then continue with the below steps.
-
-Click `Ok` and restart your computer.
-
-Open Microsoft Store, search for `Windows Subsystem for Linux` and install it.
-
-Make sure that version **2** of WSL is set as default by executing the below command in Windows Terminal:
-
-```shell
-wsl --set-default-version 2
-```
-
-To test, run again the following command:
-
-```shell
-wsl -v
-```
-
-This time the output should display `WSL version: 2.x.x.x`, which means that your system is ready for using **WSL2** and you can proceed to [install 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/).
@@ -1,251 +1,6 @@
-# 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 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.
 
-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 <distro-name>` after replacing `<distro-name>` 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 <Distro>'.
-
-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: <some-reason>` 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.
-[<your-alma-linux-10-username>@<your-device-name> <your-windows-username>]$
-```
-
-## 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: <https://docs.dotkernel.org/development/v2/setup/installation/>