Skip to content

Rewrite the landing page and shrink the duplicated wsl/ install guide #135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arhimede merged 2 commits into from
Sep 25, 2026
+22 −298
Merged

Rewrite the landing page and shrink the duplicated wsl/ install guide #135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c68098
Rewrite the landing page and shrink the duplicated wsl/ install guide
bidi47 Sep 24, 2026
e6ca476
updated readme
bidi47 Sep 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 18 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/).
253 changes: 4 additions & 249 deletions wsl/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/>
Loading