Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ 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 AlmaLinux9](wsl/README.md).
If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux10](wsl/README.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should be consistent
it's Almalinux and not AlmaLinux

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

later edit: the official name is AlmaLinux


## Install WSL2

Expand Down Expand Up @@ -57,4 +57,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 AlmaLinux9](wsl/README.md).
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 AlmaLinux10](wsl/README.md).
4 changes: 2 additions & 2 deletions docs/book/v1/setup/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Install the AlmaLinux9 distro by executing the below command:
wsl --install -d AlmaLinux-9
```

You should see the download progress - once finished, the output should look like this:
You should see the download progressonce finished, the output should look like this:

```text
Downloading: AlmaLinux OS 9
Expand All @@ -68,7 +68,7 @@ Changing password for user 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 previous step - else, continue with retyping your 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 stepelse, continue with retyping your password):

Next, you are asked to retype your password:

Expand Down
3 changes: 2 additions & 1 deletion docs/book/v1/setup/setup-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/rem
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:
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.
Expand Down
7 changes: 3 additions & 4 deletions docs/book/v1/virtualhosts/create-virtualhost.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# 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
Expand All @@ -9,9 +11,7 @@ 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:
Expand All @@ -20,8 +20,7 @@ Create the specified virtualhosts:
ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass
```

This process will ask for your password (set during the installation process) and then iterate over the list of configured `virtualhosts` and will output a short summary with the results.

This process will ask for your AlmaLinux10 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`.
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v1/virtualhosts/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Using this tool, you configure a virtualhost for each of your applications, and
**Example**:

* `api.dotkernel.localhost`: this could be the endpoint where you host your website's API
* `frontend.dotkernel.localhost`: this could be domain you host your website's frontend that will consume the API
* `frontend.dotkernel.localhost`: this could be subdomain where you host your website's frontend that will consume the API

In the above example, the URLs are built like this:

Expand Down
198 changes: 198 additions & 0 deletions docs/book/v2/faq.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
# Frequently asked questions

## How do I switch to a different version of PHP?

Execute the following command:

```shell
sudo dnf module switch-to php:remi-{major}.{minor} -y
```

where `{major}.{minor}` is one of the supported PHP versions: `8.4`, `8.3`, `8.2` and `8.1`.

Additionally, our setup includes predefined aliases for executing the above command.
The aliases are the following:

* `php81`: switch to PHP 8.1
* `php82`: switch to PHP 8.2
* `php83`: switch to PHP 8.3
* `php84`: switch to PHP 8.4

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

```shell
php -v
```

Depending on the selected PHP version, the output should look similar to the below:

```text
PHP 8.3.8 (cli) (built: Jun 4 2024 14:53:17) (NTS gcc x86_64)
Copyright (c) The PHP Group
Zend Engine v4.3.8, Copyright (c) Zend Technologies
```

## How do I switch to a different version of Node.js?

Execute the following commands:

```shell
sudo dnf remove nodejs -y
curl -fsSL https://rpm.nodesource.com/setup_{major}.x | sudo bash -
sudo dnf install nodejs -y
```

where `{major}` is the Node.js version you want to switch to.

Additionally, our setup includes predefined aliases for the above commands.
The aliases are the following:

* `node22`: switch to Node.js 22
* `node20`: switch to Node.js 20
* `node18`: switch to Node.js 18

After switching to a different Node.js version, test with the following command:

```shell
node -v
```

## How do I fix common permission issues?

If running your project, you encounter permission issues, follow the below steps.

### Error

> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data" is not writable...

> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data/cache" is not writable...

> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data/cache/doctrine" is not writable...

### Solution

```shell
chmod -R 777 data
```

### Error

> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/public/uploads" is not writable...

### Solution

```shell
chmod -R 777 public/uploads
```

### Error

> PHP Fatal error: Uncaught ErrorException: fopen(`<path-to-project>`/log/error-log-yyyy-mm-dd.log): Failed to open stream: Permission denied...

### Solution

```shell
chmod -R 777 log
```

## Where are the error log files?

From time to time, you are encountering various errors which are not displayed. Or you can get errors 500 in a browser.

To find the error messages, you need to read the error log files.

### Apache log files

```text
/var/log/httpd/error_log
```

### PHP-FPM log files

```text
/var/log/php-fpm/error.log
/var/log/php-fpm/www-error.log
```

## How do I update Composer?

Before updating, check your current Composer version by executing:

```shell
composer --version
```

The output should be similar to:

```text
Composer version 2.8.5 2025-01-21 15:23:40
PHP version 8.3.20 (/usr/bin/php)
Run the "diagnose" command to get more detailed diagnostics output.
```

Update Composer using its own `self-update` command:

```shell
sudo /usr/local/bin/composer self-update
```

The output should be similar to:

```text
Upgrading to version 2.8.8 (stable channel).

Use composer self-update --rollback to return to version 2.8.5
```

After updating, check again your Composer version by executing:

```shell
composer --version
```

The output should be similar to:

```text
Composer version 2.8.8 2025-04-04 16:56:46
PHP version 8.3.20 (/usr/bin/php)
Run the "diagnose" command to get more detailed diagnostics output.
```

## How do I update phpMyAdmin?

Being installed as a system package, it can be updated using the command which updates the rest of the system packages:

```shell
sudo dnf upgrade -y
```

## How do I create command aliases?

From either your terminal or file explorer, navigate to your home directory (`/home/<your-username>/`).

Using your preferred text editor, open the file: `.bash_profile` (if it does not exist, creat it first).

Move to the end of the file and enter on a new line:

```text
alias command_alias="command to execute"
```

where:

* `command_alias` is the name by which you want to call your original command
* `command to execute`: the original command to be executed on alias call

### Example

```text
alias list_files="ls -Al"
```

will create an alias called `list_files` that will run the command `ls -Al`.

Then, you can execute your custom alias in a terminal just as a regular command:

```shell
list_files
```
13 changes: 13 additions & 0 deletions docs/book/v2/introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Introduction

`dotkernel/development` is a tool that helps you prepare your development environment with the following components:

* **WSL2**: Windows Subsystem for Linux
* **AlmaLinux10**: free and open source Linux distribution
* **PHP**: general-purpose scripting language geared towards web development
* **Apache**: free and open-source cross-platform web server software
* **MariaDB**: community-developed, commercially supported fork of the MySQL relational database management system
* **Git**: distributed version control system
* **Composer**: application-level dependency manager for the PHP
* **Node.js**: JavaScript runtime environment
* **PhpMyAdmin**: open source administration tool for MySQL and MariaDB
83 changes: 83 additions & 0 deletions docs/book/v2/setup/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Install AlmaLinux10

Open `Windows Terminal`.

List the available Linux distributions (aka: _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`.
Install the AlmaLinux10 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 AlmaLinux10, 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: password updated successfully
[<your-almalinux10-username>@<your-device-name> <your-windows-username>]$
```
Loading