Skip to content

Commit ffae005

Browse files
arhimedearhimede
authored
Merge pull request #38 from dotkernel/docs
Added docs
2 parents 48efc1c + 7adb902 commit ffae005

File tree

19 files changed

+806
-207
lines changed

19 files changed

+806
-207
lines changed

‎.github/workflows/continuous-integration.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: "Continuous Integration"
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
tags:
8+
9+
jobs:
10+
ci:
11+
uses: laminas/workflow-continuous-integration/.github/workflows/[email protected]

‎.github/workflows/docs-build.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: docs-build
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
jobs:
9+
build-deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Build Docs
13+
uses: dotkernel/documentation-theme/github-actions/docs@main
14+
env:
15+
DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
16+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
1-
# Admin-specific stuff:
21
.idea
2+
composer.lock
3+
docs/html
4+
documentation-theme
5+
vendor

‎README.md‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
1-
## Install development environment
1+
# Install development environment
2+
23
This collection of scripts provides multiple ways of creating and maintaining your development environment.
34

5+
## Prerequisites
6+
7+
If you're not already using it, we recommend you to install
8+
[Windows Terminal](https://www.microsoft.com/en-US/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab).
9+
10+
It's a modern tool that incorporates the power of multiple already known command-line applications like
11+
`Windows PowerShell`, `Linux shell`, and more...
412

5-
### Prerequisites
6-
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).
7-
It's a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more...
13+
## How it works?
814

15+
Choose a tool from the below list, and we will guide you through the steps that will install and configure it for you.
916

10-
### How it works?
11-
Choose a tool from the below list, and we will guide you through the steps that will install and configure it for you.
12-
* [WSL](wsl/README.md)
13-
* [Docker](docker/README.md)
17+
- [WSL](wsl/README.md)
18+
- [Docker](docker/README.md)

‎composer.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "dotkernel/development",
3+
"description": "Set up development environment using Ansible+WSL2/Docker.",
4+
"type": "metapackage",
5+
"license": "MIT",
6+
"authors": [
7+
{
8+
"name": "DotKernel Team",
9+
"email": "[email protected]"
10+
}
11+
],
12+
"require": {}
13+
}

‎docs/book/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# ../../README.md

‎docs/book/v1/faq.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Frequently asked questions
2+
3+
## How do I switch to a different version of PHP?
4+
5+
Execute the following command:
6+
7+
```shell
8+
sudo dnf module switch-to php:remi-{major}.{minor} -y
9+
```
10+
11+
where `{major}.{minor}` is one of the supported PHP versions: `8.3`, `8.2`, `8.1`, `8.0` and `7.4`.
12+
13+
Additionally, our setup includes predefined aliases for executing the above command.
14+
The aliases are the following:
15+
16+
- `php74`: switch to PHP 7.4
17+
- `php80`: switch to PHP 8.0
18+
- `php81`: switch to PHP 8.1
19+
- `php82`: switch to PHP 8.2
20+
- `php83`: switch to PHP 8.3
21+
22+
After switching to a different PHP version, test with the following command:
23+
24+
```shell
25+
php -v
26+
```
27+
28+
Depending on the selected PHP version, the output should look similar to the below:
29+
30+
```text
31+
PHP 8.3.8 (cli) (built: Jun 4 2024 14:53:17) (NTS gcc x86_64)
32+
Copyright (c) The PHP Group
33+
Zend Engine v4.3.8, Copyright (c) Zend Technologies
34+
```
35+
36+
## How do I switch to a different version of Node.js?
37+
38+
Execute the following commands:
39+
40+
```shell
41+
sudo dnf remove nodejs -y
42+
curl -fsSL https://rpm.nodesource.com/setup_{major}.x | sudo bash -
43+
sudo dnf install nodejs -y
44+
```
45+
46+
where `{major}` is the Node.js version you want to switch to.
47+
48+
Additionally, our setup includes predefined aliases for the above commands.
49+
The aliases are the following:
50+
51+
- `node22`: switch to Node.js 22
52+
- `node20`: switch to Node.js 20
53+
- `node18`: switch to Node.js 18
54+
55+
After switching to a different Node.js version, test with the following command:
56+
57+
```shell
58+
node -v
59+
```
60+
61+
## How do I fix common permission issues?
62+
63+
If running your project you encounter permission issues, follow the below steps.
64+
65+
### Error
66+
67+
> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data" is not writable...
68+
69+
> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data/cache" is not writable...
70+
71+
> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/data/cache/doctrine" is not
72+
> writable...
73+
74+
### Solution
75+
76+
```shell
77+
chmod -R 777 data
78+
```
79+
80+
### Error
81+
82+
> PHP Fatal error: Uncaught InvalidArgumentException: The directory "`<path-to-project>`/public/uploads" is not
83+
> writable...
84+
85+
### Solution
86+
87+
```shell
88+
chmod -R 777 public/uploads
89+
```
90+
91+
### Error
92+
93+
> PHP Fatal error: Uncaught ErrorException: fopen(`<path-to-project>`/log/error-log-yyyy-mm-dd.log): Failed to open
94+
> stream: Permission denied...
95+
96+
### Solution
97+
98+
```shell
99+
chmod -R 777 log
100+
```
101+
102+
## How do I create command aliases?
103+
104+
From either your terminal or file explorer, navigate to your home directory (`/home/<your-username>/`).
105+
106+
Using your preferred text editor, open the file: `.bash_profile` (if it does not exist, creat it first).
107+
108+
Move to the end of the file and enter on a new line:
109+
110+
```text
111+
alias command_alias="command to execute"
112+
```
113+
114+
where:
115+
116+
- `command_alias` is the name by which you want to call your original command
117+
- `command to execute`: the original command to be executed on alias call
118+
119+
### Example
120+
121+
```text
122+
alias list_files="ls -Al"
123+
```
124+
125+
will create an alias called `list_files` that will run the command `ls -Al`.
126+
127+
Then, you can execute your custom alias in a terminal just as a regular command:
128+
129+
```shell
130+
list_files
131+
```

‎docs/book/v1/introduction.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Introduction
2+
3+
`dotkernel/development` is a tool that helps you prepare your development environment with the following components:
4+
5+
- `WSL2` - Windows Subsystem for Linux
6+
- `AlmaLinux9` - free and open source Linux distribution
7+
- `PHP` - general-purpose scripting language geared towards web development
8+
- `Apache` - free and open-source cross-platform web server software
9+
- `MariaDB` - community-developed, commercially supported fork of the MySQL relational database management system
10+
- `Git` - distributed version control system
11+
- `Composer` - application-level dependency manager for the PHP
12+
- `Node.js` - JavaScript runtime environment
13+
- `PhpMyAdmin` - open source administration tool for MySQL and MariaDB

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

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Installation
2+
3+
## Install AlmaLinux 9
4+
5+
Open Microsoft Store, in the search box type in: `AlmaLinux` and hit `Enter`.
6+
7+
From the results, select **AlmaLinux 9** - this will take you to **AlmaLinux 9**'s app page.
8+
9+
On this page, locate and click the `Install` button - this will download **AlmaLinux 9** WSL image on your system.
10+
11+
Once the download has finished, the `Install` button is replaced by an `Open` button - clicking it will open
12+
`Windows Terminal`.
13+
14+
Here you will be asked to fill in your username (for example `dotkernel`):
15+
16+
```text
17+
Installing, this may take a few minutes...
18+
Please create a default UNIX user account. The username does not need to match your Windows username.
19+
For more information visit: https://aka.ms/wslusers
20+
Enter new UNIX username:
21+
```
22+
23+
Next, you are prompted to enter a password to use with your username (you will not see what you are typing, that's a
24+
security measure in Linux regarding passwords):
25+
26+
```text
27+
Enter new UNIX username: dotkernel.
28+
Changing password for user dotkernel.
29+
New password:
30+
```
31+
32+
Depending on the strength of your password, you might see one of the following messages (if you want to choose a
33+
different password, hit `Enter` and you are taken back to previous step - else, continue with retyping your password).
34+
35+
```text
36+
BAD PASSWORD: The password fails the dictionary check - it is based on a dictionary word
37+
BAD PASSWORD: The password is a palindrome
38+
```
39+
40+
Next, you are asked to retype your password:
41+
42+
```text
43+
Retype new password:
44+
```
45+
46+
Finally, you should see the following message:
47+
48+
```text
49+
passwd: all authentication tokens updated successfully.
50+
Installation successful!
51+
[dotkernel@hostname:~]$
52+
```
53+
54+
## Setup the packages in AlmaLinux 9
55+
56+
Install requirements:
57+
58+
```shell
59+
sudo dnf install epel-release dnf-utils http://rpms.remirepo.net/enterprise/remi-release-9.rpm -y
60+
```
61+
62+
Update/Upgrade system packages:
63+
64+
```shell
65+
sudo dnf upgrade -y
66+
```
67+
68+
Now, install the latest version of **Ansible**:
69+
70+
```shell
71+
sudo dnf install ansible -y
72+
```
73+
74+
Clone `dotkernel/development` into your home directory:
75+
76+
```shell
77+
git clone https://github.com/dotkernel/development.git
78+
```
79+
80+
Move inside the directory `development/wsl`:
81+
82+
```shell
83+
cd ~/development/wsl/
84+
```
85+
86+
Using your preferred text editor, open `config.yml` where you must fill in the empty fields.
87+
88+
Save and close the file.
89+
90+
Install requirements and initialize systemd by running the below Ansible command:
91+
92+
```shell
93+
ansible-playbook -i hosts install.yml --ask-become-pass
94+
```
95+
96+
The installation process will ask for your password (set during the installation process) and will iterate over each
97+
task in the playbook and will output a short summary with the results.
98+
99+
At this step, **AlmaLinux 9** needs to be restarted - quit it by pressing `Control` + `d`.
100+
101+
Open `Windows Terminal`.
102+
103+
Stop **AlmaLinux 9**:
104+
105+
```shell
106+
wsl -t AlmaLinux9
107+
```
108+
109+
Start **AlmaLinux 9**:
110+
111+
```shell
112+
wsl -d AlmaLinux9
113+
```
114+
115+
Move inside the directory `development/wsl`:
116+
117+
```shell
118+
cd ~/development/wsl/
119+
```
120+
121+
Continue installation by running the below Ansible command:
122+
123+
```shell
124+
ansible-playbook -i hosts install.yml --ask-become-pass
125+
```
126+
127+
The installation process will ask for your password (set during the installation process) and will iterate over each
128+
task in the playbook and will output a short summary with the results.
129+
130+
Now check if everything works by opening in your browser:
131+
132+
- [http://localhost/](http://localhost/) - Apache's default home page
133+
- [http://localhost/info.php](http://localhost/info.php) - PHP info page
134+
- [http://localhost/phpmyadmin/](http://localhost/phpmyadmin/) - PhpMyAdmin (login with `root` + the root password you
135+
configured in `config.yml` under `mariadb` -> `root_password`)
136+
137+
The installation is complete, your **AlmaLinux 9** development environment is ready to use.
138+
139+
## Running AlmaLinux 9
140+
141+
Open `Windows Terminal`.
142+
143+
Start **AlmaLinux 9**:
144+
145+
```shell
146+
wsl -d AlmaLinux9
147+
```
148+
149+
### Note
150+
151+
> In order to run your applications using WSL2, you always need to be connected to your AlmaLinux9 distribution.
152+
> For this, all you need to do is to keep open an instance of Windows Terminal that is connected to it.

0 commit comments

Comments
 (0)