Merge pull request #38 from dotkernel/docs

Added docs

.github/workflows/continuous-integration.yml

@@ -0,0 +1,11 @@
+name: "Continuous Integration"
+
+on:
+  pull_request:
+  push:
+    branches:
+    tags:
+
+jobs:
+  ci:
+    uses: laminas/workflow-continuous-integration/.github/workflows/[email protected]

.github/workflows/docs-build.yml

@@ -0,0 +1,16 @@
+name: docs-build
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build Docs
+        uses: dotkernel/documentation-theme/github-actions/docs@main
+        env:
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,2 +1,5 @@
-# Admin-specific stuff:
 .idea
+composer.lock
+docs/html
+documentation-theme
+vendor

README.md

@@ -1,13 +1,18 @@
-## Install development environment
+# Install development environment
+
 This collection of scripts provides multiple ways of creating and maintaining your development environment.
 
+## Prerequisites
+
+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).
+
+It's a modern tool that incorporates the power of multiple already known command-line applications like
+`Windows PowerShell`, `Linux shell`, and more...
 
-### Prerequisites
-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).
-It's a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
+## How it works?
 
+Choose a tool from the below list, and we will guide you through the steps that will install and configure it for you.
 
-### How it works?
-Choose a tool from the below list, and we will guide you through the steps that will install and configure it for you. 
-* [WSL](wsl/README.md)
-* [Docker](docker/README.md)
+- [WSL](wsl/README.md)
+- [Docker](docker/README.md)

composer.json

@@ -0,0 +1,13 @@
+{
+    "name": "dotkernel/development",
+    "description": "Set up development environment using Ansible+WSL2/Docker.",
+    "type": "metapackage",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "DotKernel Team",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {}
+}

docs/book/index.md

@@ -0,0 +1 @@
+# ../../README.md

docs/book/v1/faq.md

@@ -0,0 +1,131 @@
+# 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.3`, `8.2`, `8.1`, `8.0` and `7.4`.
+
+Additionally, our setup includes predefined aliases for executing the above command.
+The aliases are the following:
+
+- `php74`: switch to PHP 7.4
+- `php80`: switch to PHP 8.0
+- `php81`: switch to PHP 8.1
+- `php82`: switch to PHP 8.2
+- `php83`: switch to PHP 8.3
+
+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
+```
+
+## 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
+```

docs/book/v1/introduction.md

@@ -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
+- `AlmaLinux9` - 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

docs/book/v1/setup/installation.md

@@ -0,0 +1,152 @@
+# Installation
+
+## Install AlmaLinux 9
+
+Open Microsoft Store, in the search box type in: `AlmaLinux` and hit `Enter`.
+
+From the results, select **AlmaLinux 9** - this will take you to **AlmaLinux 9**'s app page.
+
+On this page, locate and click the `Install` button - this will download **AlmaLinux 9** WSL image on your system.
+
+Once the download has finished, the `Install` button is replaced by an `Open` button - clicking it will open
+`Windows Terminal`.
+
+Here you will be asked to fill in your username (for example `dotkernel`):
+
+```text
+Installing, this may take a few minutes...
+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:
+```
+
+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):
+
+```text
+Enter new UNIX username: dotkernel.
+Changing password for user dotkernel.
+New password:
+```
+
+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).
+
+```text
+BAD PASSWORD: The password fails the dictionary check - it is based on a dictionary word
+BAD PASSWORD: The password is a palindrome
+```
+
+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.
+Installation successful!
+[dotkernel@hostname:~]$
+```
+
+## Setup the packages in AlmaLinux 9
+
+Install requirements:
+
+```shell
+sudo dnf install epel-release dnf-utils http://rpms.remirepo.net/enterprise/remi-release-9.rpm -y
+```
+
+Update/Upgrade system packages:
+
+```shell
+sudo dnf upgrade -y
+```
+
+Now, install the latest version of **Ansible**:
+
+```shell
+sudo dnf install ansible -y
+```
+
+Clone `dotkernel/development` into your home directory:
+
+```shell
+git clone https://github.com/dotkernel/development.git
+```
+
+Move inside the directory `development/wsl`:
+
+```shell
+cd ~/development/wsl/
+```
+
+Using your preferred text editor, open `config.yml` where you must fill in the empty fields.
+
+Save and close the file.
+
+Install requirements and initialize systemd by running the below Ansible command:
+
+```shell
+ansible-playbook -i hosts install.yml --ask-become-pass
+```
+
+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.
+
+At this step, **AlmaLinux 9** needs to be restarted - quit it by pressing `Control` + `d`.
+
+Open `Windows Terminal`.
+
+Stop **AlmaLinux 9**:
+
+```shell
+wsl -t AlmaLinux9
+```
+
+Start **AlmaLinux 9**:
+
+```shell
+wsl -d AlmaLinux9
+```
+
+Move inside the directory `development/wsl`:
+
+```shell
+cd ~/development/wsl/
+```
+
+Continue installation by running the below Ansible command:
+
+```shell
+ansible-playbook -i hosts install.yml --ask-become-pass
+```
+
+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.
+
+Now 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 9** development environment is ready to use.
+
+## Running AlmaLinux 9
+
+Open `Windows Terminal`.
+
+Start **AlmaLinux 9**:
+
+```shell
+wsl -d AlmaLinux9
+```
+
+### Note
+
+> In order to run your applications using WSL2, you always need to be connected to your AlmaLinux9 distribution.
+> For this, all you need to do is to keep open an instance of Windows Terminal that is connected to it.