Skip to content

Issue #92: Made distro setup page less tied to WSL 2 #96

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
merged 3 commits into from
Oct 1, 2025
Merged

Issue #92: Made distro setup page less tied to WSL 2 #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5b64b25
Issue #92: Made distro setup page less tied to WSL 2
alexmerlin Oct 1, 2025
b75846a
Issue #92: Made distro setup page less tied to WSL 2
alexmerlin Oct 1, 2025
534c572
Issue #92: Made distro setup page less tied to WSL 2
alexmerlin Oct 1, 2025
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
19 changes: 19 additions & 0 deletions docs/book/v1/running.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Running AlmaLinux 9 on WSL 2

Open `Windows Terminal`.

Start **AlmaLinux 9** by executing:

```shell
wsl -d AlmaLinux-9
```

OR

Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-9`.
This will open a new tab connected to **AlmaLinux 9**.

> To run your applications using WSL 2, you always need to be connected to your **AlmaLinux 9** 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.
6 changes: 3 additions & 3 deletions docs/book/v1/setup/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# AlmaLinux 9 Installation
# Install AlmaLinux 9 on WSL 2

Before proceeding with the installation, we need to make sure that no other WSL2 distribution (aka: _distro_) is running.
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.

Open `Windows Terminal`.

## Stop other WSL2 distros
## Stop other WSL 2 distros

List all installed distros:

Expand Down
34 changes: 8 additions & 26 deletions docs/book/v1/setup/setup-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# AlmaLinux 9 Setup

> We recommend the use of [Hetzner Cloud via our referral link](https://hetzner.cloud/?ref=HYu6z4XGfkcP) for development thanks to the initial € 20 free [Hetzner Cloud credit](https://www.hetzner.com/legal/referrals).
> The instructions below also work without using WSL.

Install system packages:
Update/Upgrade system packages:

```shell
sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y
sudo dnf upgrade -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).
Expand All @@ -23,10 +23,10 @@ Administrator. It usually boils down to these three things:

Input your **AlmaLinux 9** password and hit `Enter`.

Update/Upgrade system packages:
Install system packages:

```shell
sudo dnf upgrade -y
sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y
```

Now, install the latest version of **Ansible**:
Expand Down Expand Up @@ -72,30 +72,12 @@ The installation process will ask for your **AlmaLinux 9** password, then iterat

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 9** development environment is ready to use.

> Restart your `Windows Terminal` to find a new option in the tab selector, called **AlmaLinux-9** - clicking it will open a new tab connected to **AlmaLinux 9**.

## Running AlmaLinux 9

Open `Windows Terminal`.

Start **AlmaLinux 9** by executing:

```shell
wsl -d AlmaLinux-9
```

OR

Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-9`.
This will open a new tab connected to **AlmaLinux 9**.

### Note

> To run your applications using WSL2, you always need to be connected to your **AlmaLinux 9** distribution.
> For this, all you need to do is to keep open an instance of Windows Terminal that is connected to it.
> If you are using WSL 2, restart your `Windows Terminal` to find a new option in the tab selector, called **AlmaLinux-9** - clicking it will open a new tab connected to **AlmaLinux 9**.
12 changes: 6 additions & 6 deletions docs/book/v1/setup/system-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AlmaLinux 9 System requirements
# System requirements for AlmaLinux 9 on WSL 2

Open `Windows Terminal` and execute the following command:

Expand All @@ -18,13 +18,13 @@ 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 **WSL2** and can proceed to [install AlmaLinux 9](installation.md).
If the output starts with `WSL version: 2.x.x.x`, you are ready to use WSL 2 and can proceed to [install AlmaLinux 9](installation.md).

## Install WSL2

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.
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 WSL2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
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`.
This will open a window where you can turn Windows features on/off.
Make sure that the below features are activated (checked):

Expand All @@ -38,7 +38,7 @@ 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:
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
Expand All @@ -50,4 +50,4 @@ To test, run again the following command:
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 9](installation.md).
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 9](installation.md).
19 changes: 19 additions & 0 deletions docs/book/v2/running.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Running AlmaLinux 10 on WSL 2

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.
6 changes: 3 additions & 3 deletions docs/book/v2/setup/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# AlmaLinux 10 Installation
# Install AlmaLinux 10 on WSL 2

Before proceeding with the installation, we need to make sure that no other WSL2 distribution (aka: _distro_) is running.
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.

Open `Windows Terminal`.

## Stop other WSL2 distros
## Stop other WSL 2 distros

List all installed distros:

Expand Down
34 changes: 8 additions & 26 deletions docs/book/v2/setup/setup-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# AlmaLinux 10 Setup

> We recommend the use of [Hetzner Cloud via our referral link](https://hetzner.cloud/?ref=HYu6z4XGfkcP) for development thanks to the initial € 20 free [Hetzner Cloud credit](https://www.hetzner.com/legal/referrals).
> The instructions below also work without using WSL.

Install system packages:
Update/Upgrade system packages:

```shell
sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y
sudo dnf upgrade -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).
Expand All @@ -25,10 +25,10 @@ For security reasons, the password you type will not be visible.

Input your **AlmaLinux 10** password and hit `Enter`.

Update/Upgrade system packages:
Install system packages:

```shell
sudo dnf upgrade -y
sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %almalinux).rpm -y
```

Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections:
Expand Down Expand Up @@ -78,30 +78,12 @@ The installation process will ask for your **AlmaLinux 10** password, then itera

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.

> 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**.

## Running AlmaLinux 10

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**.

### Note

> To run your applications using WSL2, you always need to be connected to your **AlmaLinux 10** distribution.
> For this, all you need to do is to keep open an instance of Windows Terminal that is connected to it.
> 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**.
14 changes: 7 additions & 7 deletions docs/book/v2/setup/system-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AlmaLinux 10 System requirements
# System requirements for AlmaLinux 10 on WSL 2

Open `Windows Terminal` and execute the following command:

Expand All @@ -18,13 +18,13 @@ 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 **WSL2** and can proceed to [install AlmaLinux 10](installation.md).
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).

## Install WSL2
## 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 WSL2.
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 WSL2, open the `Run` prompt by pressing `Win` + `r`, type `OptionalFeatures` in the dialog and press `Enter`.
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`.
This will open a window where you can turn Windows features on/off.
Make sure that the below features are activated (checked):

Expand All @@ -38,7 +38,7 @@ 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:
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
Expand All @@ -50,4 +50,4 @@ To test, run again the following command:
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](installation.md).
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).
2 changes: 2 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ nav:
- System Requirements: v2/setup/system-requirements.md
- Installation: v2/setup/installation.md
- Setup Packages: v2/setup/setup-packages.md
- Running on WSL 2: v2/running.md
- Virtualhosts:
- Overview: v2/virtualhosts/overview.md
- Create virtualhost: v2/virtualhosts/create-virtualhost.md
Expand All @@ -24,6 +25,7 @@ nav:
- System Requirements: v1/setup/system-requirements.md
- Installation: v1/setup/installation.md
- Setup Packages: v1/setup/setup-packages.md
- Running on WSL 2: v1/running.md
- Virtualhosts:
- Overview: v1/virtualhosts/overview.md
- Create virtualhost: v1/virtualhosts/create-virtualhost.md
Expand Down