Skip to content

Commit bbf1eaf

Browse files
alexmerlinalexmerlin
committed
Issue #58: Implement one distro per branch structure
Signed-off-by: alexmerlin <[email protected]>
1 parent e0263e0 commit bbf1eaf

File tree

38 files changed

+402
-599
lines changed

38 files changed

+402
-599
lines changed

‎README.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,60 @@
1-
# Development environment
1+
# WSL2 development environment
22

3-
This is a collection of Ansible scripts allowing the creation and maintenance of your WSL2 development environment.
3+
This is a collection of Ansible scripts helping with the creation and maintenance of your WSL2 development environment.
44

5-
## Prerequisites
5+
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).
6+
It is a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
67

7-
If you're not already using it, we recommend you to install [Windows Terminal](https://www.microsoft.com/en-US/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab).
8+
## Check if WLS2 is already available
89

9-
It's a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
10+
Open `Windows Terminal` and execute the following command:
1011

11-
## Setup
12+
```shell
13+
wsl -v
14+
```
1215

13-
Go to the [WSL2](wsl/README.md) setup page.
16+
The output should look similar to this:
17+
18+
```text
19+
WSL version: 2.2.4.0
20+
Kernel version: 5.15.153.1-2
21+
WSLg version: 1.0.61
22+
MSRDC version: 1.2.5326
23+
Direct3D version: 1.611.1-81528511
24+
DXCore version: 10.0.26091.1-240325-1447.ge-release
25+
Windows version: 10.0.22631.3737
26+
```
27+
28+
If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux9](wsl/README.md).
29+
30+
## Install WSL2
31+
32+
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.
33+
34+
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`.
35+
This will open a window where you can turn Windows features on/off.
36+
Make sure that the below features are activated (checked):
37+
38+
* `Hyper-V` (including its sub-features)
39+
* `Virtual Machine Platform`
40+
* `Windows Subsystem for Linux`
41+
42+
> 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.
43+
44+
Click `Ok` and restart your computer.
45+
46+
Open Microsoft Store, search for `Windows Subsystem for Linux` and install it.
47+
48+
Make sure that version **2** of WSL is set as default by executing the below command in Windows Terminal:
49+
50+
```shell
51+
wsl --set-default-version 2
52+
```
53+
54+
To test, run again the following command:
55+
56+
```shell
57+
wsl -v
58+
```
59+
60+
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 AlmaLinux9](wsl/README.md).

‎docs/book/v1/faq.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The aliases are the following:
1616
* `php81`: switch to PHP 8.1
1717
* `php82`: switch to PHP 8.2
1818
* `php83`: switch to PHP 8.3
19-
* `php83`: switch to PHP 8.4
19+
* `php84`: switch to PHP 8.4
2020

2121
After switching to a different PHP version, test with the following command:
2222

‎docs/book/v1/setup/installation.md‎

Lines changed: 53 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,74 @@
1-
# Installation
1+
# Install AlmaLinux9
22

3-
## Install AlmaLinux9
3+
Open `Windows Terminal`.
44

5-
Open Microsoft Store, in the search box type in: `AlmaLinux` and hit `Enter`.
5+
List the available Linux distributions (aka: _distros_) by executing:
66

7-
From the results, select **AlmaLinux OS 9** this will take you to **AlmaLinux9**'s app page.
7+
```shell
8+
wsl --list --online
9+
```
10+
11+
Depending on the list of distros available at the moment you run the command, the output should look similar to the below:
12+
13+
```text
14+
The following is a list of valid distributions that can be installed.
15+
Install using 'wsl.exe --install <Distro>'.
16+
17+
NAME FRIENDLY NAME
18+
AlmaLinux-8 AlmaLinux OS 8
19+
AlmaLinux-9 AlmaLinux OS 9
20+
AlmaLinux-Kitten-10 AlmaLinux OS Kitten 10
21+
AlmaLinux-10 AlmaLinux OS 10
22+
Debian Debian GNU/Linux
23+
FedoraLinux-42 Fedora Linux 42
24+
SUSE-Linux-Enterprise-15-SP5 SUSE Linux Enterprise 15 SP5
25+
SUSE-Linux-Enterprise-15-SP6 SUSE Linux Enterprise 15 SP6
26+
Ubuntu Ubuntu
27+
Ubuntu-24.04 Ubuntu 24.04 LTS
28+
archlinux Arch Linux
29+
kali-linux Kali Linux Rolling
30+
openSUSE-Tumbleweed openSUSE Tumbleweed
31+
openSUSE-Leap-15.6 openSUSE Leap 15.6
32+
Ubuntu-18.04 Ubuntu 18.04 LTS
33+
Ubuntu-20.04 Ubuntu 20.04 LTS
34+
Ubuntu-22.04 Ubuntu 22.04 LTS
35+
OracleLinux_7_9 Oracle Linux 7.9
36+
OracleLinux_8_7 Oracle Linux 8.7
37+
OracleLinux_9_1 Oracle Linux 9.1
38+
```
839

9-
On this page, locate and click the `Install` button - this will download **AlmaLinux9** WSL2 image on your system.
40+
Note the two columns: **NAME** and **FRIENDLY NAME**.
41+
To install a specific distro, use the value from the **NAME** column, in this case: `AlmaLinux-9`.
42+
Install the AlmaLinux9 distro by executing the below command:
1043

11-
Once the download has finished, the `Install` button is replaced by an `Open` button - clicking it will open `Windows Terminal`.
44+
```shell
45+
wsl --install -d AlmaLinux-9
46+
```
1247

13-
Here you will be asked to fill in your username (for example `dotkernel`):
48+
You should see the download progress - once finished, the output should look like this:
1449

1550
```text
16-
Installing, this may take a few minutes...
51+
Downloading: AlmaLinux OS 9
52+
Installing: AlmaLinux OS 9
53+
Distribution successfully installed. It can be launched via 'wsl.exe -d AlmaLinux-9'
54+
Launching AlmaLinux-9...
1755
Please create a default UNIX user account. The username does not need to match your Windows username.
1856
For more information visit: https://aka.ms/wslusers
1957
Enter new UNIX username:
2058
```
2159

22-
Next, you are prompted to enter a password to use with your username (you will not see what you are typing, that's a security measure in Linux regarding passwords):
60+
As per the last line, the installation process now prompts you to enter a username.
61+
This is the username you will use inside AlmaLinux9, and it can be any alphanumeric string (for example `dotkernel`):
2362

24-
```text
63+
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):
64+
65+
```shell
2566
Enter new UNIX username: dotkernel.
2667
Changing password for user dotkernel.
2768
New password:
2869
```
2970

30-
Depending on the strength of your password, you might see one of the following messages (if you want to choose a different password, hit `Enter` and you are taken back to previous step - else, continue with retyping your password).
31-
32-
```text
33-
BAD PASSWORD: The password fails the dictionary check - it is based on a dictionary word
34-
BAD PASSWORD: The password is a palindrome
35-
```
71+
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 previous step - else, continue with retyping your password):
3672

3773
Next, you are asked to retype your password:
3874

@@ -44,6 +80,5 @@ Finally, you should see the following message:
4480

4581
```text
4682
passwd: all authentication tokens updated successfully.
47-
Installation successful!
48-
[dotkernel@hostname:~]$
83+
[<your-almalinux9-username>@<your-device-name> <your-windows-username>]$
4984
```

‎docs/book/v1/setup/setup-packages.md‎

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,97 @@
1-
# Setup the packages in AlmaLinux9
1+
# Setup AlmaLinux9
22

3-
Install system requirements:
3+
Install system packages:
44

55
```shell
66
sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-9.rpm -y
77
```
88

9-
Update/Upgrade system packages:
9+
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).
1010

11-
```shell
12-
sudo dnf upgrade -y
13-
```
11+
```text
12+
We trust you have received the usual lecture from the local System Administrator. It usually boils down to these three things:
1413
15-
Now, install the latest version of **Ansible**:
14+
#1) Respect the privacy of others.
15+
#2) Think before you type.
16+
#3) With great power comes great responsibility.
1617
17-
```shell
18-
sudo dnf install ansible -y
18+
[sudo] password for dotkernel:
1919
```
2020

21-
Clone `dotkernel/development` into your home directory:
21+
Input your AlmaLinux9 password and hit `Enter`.
22+
23+
Update/Upgrade system packages:
2224

2325
```shell
24-
git clone https://github.com/dotkernel/development.git
26+
sudo dnf upgrade -y
2527
```
2628

27-
Move inside the directory `development/wsl`:
29+
Now, install the latest version of **Ansible**:
2830

2931
```shell
30-
cd ~/development/wsl/
32+
sudo dnf install ansible -y
3133
```
3234

33-
Duplicate `config.yml.dist` as `config.yml`.
34-
35-
Using your preferred text editor, open `config.yml` and fill in the empty fields.
36-
37-
Save and close the file.
38-
39-
Install requirements and initialize systemd by running the below Ansible command:
35+
Move inside your home directory (it is `/home/` followed by your AlmaLinux9 username, for example: `/home/dotkernel`):
4036

4137
```shell
42-
ansible-playbook -i hosts install.yml --ask-become-pass
38+
cd ~
4339
```
4440

45-
The installation process will ask for your password (set during the installation process) and will iterate over each task in the playbook and will output a short summary with the results.
46-
47-
At this step, **AlmaLinux9** needs to be restarted; quit it by pressing `Control` + `d`.
48-
49-
Open `Windows Terminal`.
50-
51-
Stop **AlmaLinux9**:
41+
Clone the `almalinux9` branch of the `dotkernel/development` repository:
5242

5343
```shell
54-
wsl -t AlmaLinux9
44+
git clone --branch almalinux9 --single-branch https://github.com/dotkernel/development.git
5545
```
5646

57-
Start **AlmaLinux9**:
47+
Move inside the directory `development/wsl`:
5848

5949
```shell
60-
wsl -d AlmaLinux9
50+
cd development/wsl/
6151
```
6252

63-
Move inside the directory `development/wsl`:
53+
Duplicate `config.yml.dist` as `config.yml`:
6454

6555
```shell
66-
cd ~/development/wsl/
56+
cp config.yml.dist config.yml
6757
```
6858

69-
Continue the installation by running the below Ansible command:
59+
Using your preferred text editor, open `config.yml` and fill in the empty fields.
60+
Save and close the file.
61+
62+
Install components by running the below Ansible command:
7063

7164
```shell
7265
ansible-playbook -i hosts install.yml --ask-become-pass
7366
```
7467

75-
The installation process will ask for your password (set during the installation process) and will iterate over each task in the playbook and will output a short summary with the results.
68+
The installation process will ask for your AlmaLinux9 password, then iterate over each task in the playbook and output a short summary with the results.
7669

77-
Now check if everything works by opening in your browser:
70+
Once finished, check if everything works by opening in your browser:
7871

7972
* [http://localhost/](http://localhost/): Apache's default home page
8073
* [http://localhost/info.php](http://localhost/info.php): PHP info page
8174
* [http://localhost/phpmyadmin/](http://localhost/phpmyadmin/): PhpMyAdmin (login with `root` + the root password you configured in `config.yml` under `mariadb` -> `root_password`)
8275

83-
The installation is complete, your **AlmaLinux9** development environment is ready to use.
76+
The installation is complete, your AlmaLinux9 development environment is ready to use.
77+
78+
> 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 **AlmaLinux9**.
8479
8580
## Running AlmaLinux9
8681

8782
Open `Windows Terminal`.
8883

89-
Start **AlmaLinux9**:
84+
Start AlmaLinux9 by executing:
9085

9186
```shell
9287
wsl -d AlmaLinux9
9388
```
9489

90+
OR
91+
92+
Locate the app selector dropdown in `Windows Terminal`'s title bar and click `AlmaLinux-9`.
93+
This will open a new tab connected to AlmaLinux9.
94+
9595
### Note
9696

9797
> To run your applications using WSL2, you always need to be connected to your AlmaLinux9 distribution.

‎docs/book/v1/setup/system-requirements.md‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
1-
# System Requirements
1+
# System requirements
22

3-
First, you need to check if your system is ready for using **WSL2**. Open `Windows Terminal` and execute the following command:
3+
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).
4+
It is a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
5+
6+
## Check if WLS2 is already available
7+
8+
Open `Windows Terminal` and execute the following command:
49

510
```shell
611
wsl -v
@@ -18,17 +23,15 @@ DXCore version: 10.0.26091.1-240325-1447.ge-release
1823
Windows version: 10.0.22631.3737
1924
```
2025

21-
If the output starts with `WSL version: 2.x`, you are ready to use **WSL2** and can continue with [the installation](installation.md).
26+
If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux9](installation.md).
2227

23-
Else, you need to install **WSL2** and its components as shown below.
28+
## Install WSL2
2429

25-
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**.
26-
27-
Once you know that your system can run **WSL2**, open the `Run` prompt by pressing `Win`+`r` and type in the dialog `OptionalFeatures`, then press `Enter`.
30+
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.
2831

32+
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`.
2933
This will open a window where you can turn Windows features on/off.
30-
31-
Make sure the next features are activated (checked):
34+
Make sure that the below features are activated (checked):
3235

3336
* `Hyper-V` (including its sub-features)
3437
* `Virtual Machine Platform`
@@ -40,7 +43,7 @@ Click `Ok` and restart your computer.
4043

4144
Open Microsoft Store, search for `Windows Subsystem for Linux` and install it.
4245

43-
Make sure **WSL2** is set as default by executing the below command in `Windows Terminal`:
46+
Make sure that version **2** of WSL is set as default by executing the below command in Windows Terminal:
4447

4548
```shell
4649
wsl --set-default-version 2
@@ -52,4 +55,4 @@ To test, run again the following command:
5255
wsl -v
5356
```
5457

55-
This time the output should display `WSL version: 2.x`, which means that your system is ready for using **WSL2** and you can continue with the [installation](installation.md).
58+
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 AlmaLinux9](installation.md).

‎docs/book/v1/virtualhosts/create-virtualhost.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,6 @@ You will install your project under the `html` directory of your project, for ex
3535
* To run your installed projects, you need to start AlmaLinux9 first.
3636
* If you work with virtualhosts, your projects are created under `/var/www/`.
3737
* You can still run PHP scripts under the default Apache project directory, located at `/var/www/html/`.
38-
* If you encounter write permission issues, see [this guide](../faq.md#how-do-i-fix-common-permission-issues).
39-
* This tool installs PHP 8.3 by default. If you need a different version, see [this guide](../faq.md#how-do-i-switch-to-a-different-version-of-php).
40-
* This tool installs Node.js 22 by default. If you need a different version, see [this guide](../faq.md#how-do-i-switch-to-a-different-version-of-nodejs).
38+
* If you encounter write permission issues, see [this guide](https://docs.dotkernel.org/development/almalinux9/faq/#how-do-i-fix-common-permission-issues).
39+
* We install PHP 8.3 by default - if you need a different version, see [this guide](https://docs.dotkernel.org/development/almalinux9/faq/#how-do-i-switch-to-a-different-version-of-php).
40+
* We install Node.js 22 by default - if you need a different version, see [this guide](https://docs.dotkernel.org/development/almalinux9/faq/#how-do-i-switch-to-a-different-version-of-nodejs).

0 commit comments

Comments
 (0)