diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml deleted file mode 100644 index 1a7aa24..0000000 --- a/.github/workflows/docs-build.yml +++ /dev/null @@ -1,16 +0,0 @@ -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 }} diff --git a/docs/book/index.md b/docs/book/index.md deleted file mode 120000 index fe84005..0000000 --- a/docs/book/index.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/docs/book/v1/faq.md b/docs/book/v1/faq.md deleted file mode 100644 index 2815d05..0000000 --- a/docs/book/v1/faq.md +++ /dev/null @@ -1,198 +0,0 @@ -# AlmaLinux 9 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 "``/data" is not writable... - -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache" is not writable... - -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache/doctrine" is not writable... - -### Solution - -```shell -chmod -R 777 data -``` - -### Error - -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not writable... - -### Solution - -```shell -chmod -R 777 public/uploads -``` - -### Error - -> PHP Fatal error: Uncaught ErrorException: fopen(``/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//`). - -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 -``` diff --git a/docs/book/v1/setup/installation.md b/docs/book/v1/setup/installation.md deleted file mode 100644 index 849e793..0000000 --- a/docs/book/v1/setup/installation.md +++ /dev/null @@ -1,127 +0,0 @@ -# AlmaLinux 9 Installation - -Before proceeding with the installation, we need to make sure that no other WSL2 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 - -List all installed distros: - -```shell -wsl -l -v -``` - -If there is no other distro installed, you will see the below output (an empty list): - -```text - NAME STATE VERSION -``` - -In this case, you can jump to the [installation](#install-almalinux-9) section. - -If you have other distros installed, the output could look similar to the below: - -```text - NAME STATE VERSION - AlmaLinux-9 Stopped 2 -* AlmaLinux-10 Running 2 -``` - -Make sure that the **STATE** column reads **Stopped** for all distros. -If any of them reads **Running**, you must stop if first by executing `wsl -t ` after replacing `` with the name of the distro you want to stop. -Once you have stopped all distros, you can continue to the [installation](#install-almalinux-9) section. - -## Install AlmaLinux 9 - -List the available Linux 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 '. - -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-9`. - -> If you try to install a distro that is already installed, the installation process will fail: - -```text -Downloading: AlmaLinux OS 9 -Installing: AlmaLinux OS 9 -A distribution with the supplied name already exists. Use --name to choose a different name. -Error code: Wsl/InstallDistro/Service/RegisterDistro/ERROR_ALREADY_EXISTS -``` - -Install the **AlmaLinux 9** distro by executing the below command: - -```shell -wsl --install -d AlmaLinux-9 -``` - -You should see the download progress—once finished, the output should look like this: - -```text -Downloading: AlmaLinux OS 9 -Installing: AlmaLinux OS 9 -Distribution successfully installed. It can be launched via 'wsl.exe -d AlmaLinux-9' -Launching AlmaLinux-9... -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 **AlmaLinux 9**, 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. -Changing password for user dotkernel. -New password: -``` - -Depending on the strength of your password, you might get a `BAD PASSWORD: ` 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: all authentication tokens updated successfully. -[@ ]$ -``` diff --git a/docs/book/v1/setup/setup-packages.md b/docs/book/v1/setup/setup-packages.md deleted file mode 100644 index 9f40530..0000000 --- a/docs/book/v1/setup/setup-packages.md +++ /dev/null @@ -1,99 +0,0 @@ -# AlmaLinux 9 Setup - -Install system packages: - -```shell -sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-9.rpm -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). - -```text -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. - #3) With great power comes great responsibility. - -[sudo] password for dotkernel: -``` - -Input your **AlmaLinux 9** password and hit `Enter`. - -Update/Upgrade system packages: - -```shell -sudo dnf upgrade -y -``` - -Now, install the latest version of **Ansible**: - -```shell -sudo dnf install ansible -y -``` - -Move inside your home directory (it is `/home/` followed by your **AlmaLinux 9** username, for example: `/home/dotkernel`): - -```shell -cd ~ -``` - -Clone the `alma-linux-9` branch of the `dotkernel/development` repository: - -```shell -git clone --branch alma-linux-9 --single-branch https://github.com/dotkernel/development.git -``` - -Move inside the directory `development/wsl`: - -```shell -cd development/wsl/ -``` - -Duplicate `config.yml.dist` as `config.yml`: - -```shell -cp config.yml.dist config.yml -``` - -Using your preferred text editor, open `config.yml` and fill in the empty fields. -Save and close the file. - -Install components by running the below Ansible command: - -```shell -ansible-playbook -i hosts install.yml --ask-become-pass -``` - -The installation process will ask for your **AlmaLinux 9** password, then iterate over each task in the playbook and output a short summary with the results. - -Once finished, 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. - -> 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. diff --git a/docs/book/v1/setup/system-requirements.md b/docs/book/v1/setup/system-requirements.md deleted file mode 100644 index fff8c7d..0000000 --- a/docs/book/v1/setup/system-requirements.md +++ /dev/null @@ -1,53 +0,0 @@ -# AlmaLinux 9 System requirements - -Open `Windows Terminal` and execute the following command: - -```shell -wsl -v -``` - -The output should look similar to this: - -```text -WSL version: 2.2.4.0 -Kernel version: 5.15.153.1-2 -WSLg version: 1.0.61 -MSRDC version: 1.2.5326 -Direct3D version: 1.611.1-81528511 -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). - -## 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. - -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`. -This will open a window where you can turn Windows features on/off. -Make sure that the below features are activated (checked): - -* `Hyper-V` (including its sub-features) -* `Virtual Machine Platform` -* `Windows Subsystem for Linux` - -> 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. - -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: - -```shell -wsl --set-default-version 2 -``` - -To test, run again the following command: - -```shell -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). diff --git a/docs/book/v1/terminal.md b/docs/book/v1/terminal.md deleted file mode 100644 index afda13c..0000000 --- a/docs/book/v1/terminal.md +++ /dev/null @@ -1,4 +0,0 @@ -# Terminal - -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). -It is a modern tool that incorporates the power of multiple already known command-line applications like `Windows PowerShell`, `Linux shell`, and more... diff --git a/docs/book/v1/virtualhosts/create-virtualhost.md b/docs/book/v1/virtualhosts/create-virtualhost.md deleted file mode 100644 index 5104d1d..0000000 --- a/docs/book/v1/virtualhosts/create-virtualhost.md +++ /dev/null @@ -1,39 +0,0 @@ -# AlmaLinux 9 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 -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: - -```shell -ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass -``` - -This process will ask for your **AlmaLinux 9** 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`. - -> The virtualhost's document root is set to the `public` directory of the above location, for example `/var/www/example.localhost/html/public`. - -> If you want to have the DocumentRoot directly in `html` folder, you need to modify the file `/etc/httpd/sites-available/example.localhost`. - -## Good to know - -* To run your installed projects, you need to start **AlmaLinux 9** first. -* If you work with virtualhosts, your projects are created under `/var/www/`. -* You can still run PHP scripts under the default Apache project directory, located at `/var/www/html/`. -* If you encounter write permission issues, see [this guide](https://docs.dotkernel.org/development/v1/faq/#how-do-i-fix-common-permission-issues). -* We install PHP 8.3 by default—if you need a different version, see [this guide](https://docs.dotkernel.org/development/v1/faq/#how-do-i-switch-to-a-different-version-of-php). -* We install Node.js 22 by default—if you need a different version, see [this guide](https://docs.dotkernel.org/development/v1/faq/#how-do-i-switch-to-a-different-version-of-nodejs). diff --git a/docs/book/v1/virtualhosts/overview.md b/docs/book/v1/virtualhosts/overview.md deleted file mode 100644 index 8d35d9c..0000000 --- a/docs/book/v1/virtualhosts/overview.md +++ /dev/null @@ -1,18 +0,0 @@ -# AlmaLinux 9 Overview - -Virtualhosts allow developers to host multiple applications on their local system. - -Using this tool, you configure a virtualhost for each of your applications, and it will create them so that you can start working with them. - -**Example**: - -* `api.dotkernel.localhost`: this could be the endpoint where you host your website's API -* `frontend.dotkernel.localhost`: this could be the subdomain where you host your website's frontend that will consume the API - -In the above example, the URLs are built like this: - -* the subdomain is the identifier of your application (`api` / `frontend`) -* the domain is the identifier of your project (`dotkernel`) -* the TLD sends the requests to localhost where Apache will route them to their real location - -> By using the pattern `*.localhost` for any new virtualhost, you do not need to modify the `hosts` file in Windows, because these are routed by default. diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 2e1ea12..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,24 +0,0 @@ -docs_dir: docs/book -site_dir: docs/html -extra: - project: Development - current_version: v1 - versions: - - v1 -nav: - - Home: index.md - - v1: - - Terminal: v1/terminal.md - - Setup: - - System Requirements: v1/setup/system-requirements.md - - Installation: v1/setup/installation.md - - Setup Packages: v1/setup/setup-packages.md - - Virtualhosts: - - Overview: v1/virtualhosts/overview.md - - Create virtualhost: v1/virtualhosts/create-virtualhost.md - - FAQ: v1/faq.md -site_name: development -site_description: "WSL2 Development Environment" -repo_url: "https://github.com/dotkernel/development" -plugins: - - search