diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml new file mode 100644 index 0000000..26c5802 --- /dev/null +++ b/.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/continuous-integration.yml@1.x diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 0000000..1a7aa24 --- /dev/null +++ b/.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 }} diff --git a/.gitignore b/.gitignore index e0f4fb4..631061a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ -# Admin-specific stuff: .idea +composer.lock +docs/html +documentation-theme +vendor diff --git a/README.md b/README.md index 300dd98..586fe5b 100644 --- a/README.md +++ b/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) diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..a030f13 --- /dev/null +++ b/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": "team@dotkernel.com" + } + ], + "require": {} +} diff --git a/docs/book/index.md b/docs/book/index.md new file mode 100644 index 0000000..2eceefd --- /dev/null +++ b/docs/book/index.md @@ -0,0 +1 @@ +# ../../README.md diff --git a/docs/book/v1/faq.md b/docs/book/v1/faq.md new file mode 100644 index 0000000..64666e8 --- /dev/null +++ b/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 "``/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 +``` + +## 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/introduction.md b/docs/book/v1/introduction.md new file mode 100644 index 0000000..13c702b --- /dev/null +++ b/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 diff --git a/docs/book/v1/setup/installation.md b/docs/book/v1/setup/installation.md new file mode 100644 index 0000000..0020b1e --- /dev/null +++ b/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. diff --git a/docs/book/v1/setup/system-requirements.md b/docs/book/v1/setup/system-requirements.md new file mode 100644 index 0000000..1ba3196 --- /dev/null +++ b/docs/book/v1/setup/system-requirements.md @@ -0,0 +1,62 @@ +# System Requirements + +First, you need to check if your system is ready for using **WSL2**. 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`, you are ready to use **WSL2** and can continue with +[the installation](installation.md). + +Else, you need to install **WSL2** and it's components as shown below. + +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 know that your system can run **WSL2**, open the `Run` prompt by pressing `Win`+`r` and type in the dialog +`OptionalFeatures`, then press `Enter`. + +This will open a window where you can turn Windows features on/off. + +Make sure the next features are activated (checked): + +- `Hyper-V` (including its sub-features) +- `Virtual Machine Platform` +- `Windows Subsystem for Linux` + +> If any of the above features is 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 **WSL2** 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`, which means that your system is ready for using **WSL2** and you +can continue with the [installation](installation.md). diff --git a/docs/book/v1/virtualhosts/create-virtualhost.md b/docs/book/v1/virtualhosts/create-virtualhost.md new file mode 100644 index 0000000..9f64448 --- /dev/null +++ b/docs/book/v1/virtualhosts/create-virtualhost.md @@ -0,0 +1,45 @@ +# Create virtualhosts + +Move inside the directory `development/wsl`: + +```shell +cd ~/development/wsl/ +``` + +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 password (set during the installation process) and then iterate over the list of +configured `virtualhosts` and will 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 + +- In order 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](../faq.md#how-do-i-fix-common-permission-issues). +- This tool install 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). +- This tool install 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). diff --git a/docs/book/v1/virtualhosts/overview.md b/docs/book/v1/virtualhosts/overview.md new file mode 100644 index 0000000..7de6a51 --- /dev/null +++ b/docs/book/v1/virtualhosts/overview.md @@ -0,0 +1,21 @@ +# 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 domain 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 + +## Note +> 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 new file mode 100644 index 0000000..d6c2041 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,23 @@ +docs_dir: docs/book +site_dir: docs/html +extra: + project: Development + current_version: v1 + versions: + - v1 +nav: + - Home: index.md + - v1: + - Introduction: v1/introduction.md + - Setup: + - System Requirements: v1/setup/system-requirements.md + - Installation: v1/setup/installation.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 diff --git a/wsl/README.md b/wsl/README.md index 4321fca..b32592e 100644 --- a/wsl/README.md +++ b/wsl/README.md @@ -1,21 +1,26 @@ -## Install WSL development environment +# Install WSL2 development environment [< Back](../README.md) - ## Prerequisites -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 know that your machine can run WSL2, open the `Run` prompt by pressing `Win`+`r` and type in the dialog `OptionalFeatures`, then press `Enter`. +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 know that your machine can run WSL2, open the `Run` prompt by pressing `Win`+`r` and type in the dialog +`OptionalFeatures`, then press `Enter`. This will open a window where you can turn Windows features on/off. Make sure the next features are activated (checked): -* `Hyper-V` (including its sub-features) -* `Virtual Machine Platform` -* `Windows Subsystem for Linux` -> If any of the above features is 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. +- `Hyper-V` (including its sub-features) +- `Virtual Machine Platform` +- `Windows Subsystem for Linux` + +> If any of the above features is 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. @@ -23,8 +28,11 @@ Open Microsoft Store, search for `Windows Subsystem for Linux` and install it. Make sure WSL2 is set as default by executing the below command in Windows Terminal: - wsl --set-default-version 2 +```shell +wsl --set-default-version 2 +``` ## Choose the Operating System you want to use for development: -* [Ubuntu 20](os/ubuntu20/README.md) -* [AlmaLinux 9](os/almalinux9/README.md) + +- [Ubuntu 20](os/ubuntu20/README.md) +- [AlmaLinux 9](os/almalinux9/README.md) diff --git a/wsl/os/almalinux9/FAQ.md b/wsl/os/almalinux9/FAQ.md index 44063dd..3c93a32 100644 --- a/wsl/os/almalinux9/FAQ.md +++ b/wsl/os/almalinux9/FAQ.md @@ -2,88 +2,102 @@ ## How do I switch to a different version of PHP? -### Switch to PHP 8.3 +Execute the following command: -Use alias `php83` or execute: +```shell +sudo dnf module switch-to php:remi-{major}.{minor} -y +``` - sudo dnf module switch-to php:remi-8.3 -y +where `{major}.{minor}` is one of the supported PHP versions: `8.3`, `8.2`, `8.1`, `8.0` and `7.4`. -### Switch to PHP 8.2 +Additionally, our setup includes predefined aliases for executing the above command. +The aliases are the following: -Use alias `php82` or execute: +- `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 - sudo dnf module switch-to php:remi-8.2 -y +After switching to a different PHP version, test with the following command: -### Switch to PHP 8.1 +```shell +php -v +``` -Use alias `php81` or execute: +Depending on the selected PHP version, the output should look similar to the below: - sudo dnf module switch-to php:remi-8.1 -y - -### Switch to PHP 7.4 - -Use alias `php74` or execute: - - sudo dnf module switch-to php:remi-7.4 -y +```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? -### Switch to Node.js 22.x - -Use alias `node22` or execute: - - sudo dnf remove nodejs -y - curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - - sudo dnf install nodejs -y - -### Switch to Node.js 20.x +Execute the following commands: -Use alias `node20` or execute: +```shell +sudo dnf remove nodejs -y +curl -fsSL https://rpm.nodesource.com/setup_{major}.x | sudo bash - +sudo dnf install nodejs -y +``` - sudo dnf remove nodejs -y - curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - - sudo dnf install nodejs -y +where `{major}` is the Node.js version you want to switch to. -### Switch to Node.js 18.x +Additionally, our setup includes predefined aliases for the above commands. +The aliases are the following: -Use alias `node18` or execute: +- `node22`: switch to Node.js 22 +- `node20`: switch to Node.js 20 +- `node18`: switch to Node.js 18 - sudo dnf remove nodejs -y - curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash - - sudo dnf install nodejs -y +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 some permission issues, follow the below steps. +If running your project you encounter permission issues, follow the below steps. -### Errors: +### Error -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/data" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data" is not writable... -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/data/cache" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache" is not writable... -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/data/cache/doctrine" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache/doctrine" is not +> writable... -**Fix:** +### Solution - chmod -R 777 data +```shell +chmod -R 777 data +``` -### Error: +### Error -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/var/www/_example.local_/html/public/uploads" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not +> writable... -**Fix:** +### Solution - chmod -R 777 public/uploads +```shell +chmod -R 777 public/uploads +``` -### Error: +### Error -> PHP Fatal error: Uncaught ErrorException: fopen(/var/www/_example.local_/config/autoload/../../log/error-log-_yyyy-mm-dd.log_): Failed to open stream: Permission denied... +> PHP Fatal error: Uncaught ErrorException: fopen(``/log/error-log-yyyy-mm-dd.log): Failed to open +> stream: Permission denied... -**Fix:** +### Solution - chmod -R 777 log +```shell +chmod -R 777 log +``` ## How do I create command aliases? diff --git a/wsl/os/almalinux9/README.md b/wsl/os/almalinux9/README.md index fa1fa0b..b63e5d1 100644 --- a/wsl/os/almalinux9/README.md +++ b/wsl/os/almalinux9/README.md @@ -2,65 +2,86 @@ [< DotKernel: Install development environment](../../README.md) - ## Download and 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 machine. -Once the download has finished, the `Install` button is replaced by an `Open` button - clicking it will open Windows Terminal. +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`): - 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: +```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): - Enter new UNIX username: dotkernel. - Changing password for user dotkernel. - New password: +```shell +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) - BAD PASSWORD: The password fails the dictionary check - it is based on a dictionary word - BAD PASSWORD: The password is a palindrome +```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: - Retype new password: +```text +Retype new password: +``` Finally, you should see the following message: - passwd: all authentication tokens updated successfully. - Installation successful! - [dotkernel@hostname:~]$ - +```text +passwd: all authentication tokens updated successfully. +Installation successful! +[dotkernel@hostname:~]$ +``` ## Setup AlmaLinux 9 + Install requirements: - sudo dnf install epel-release dnf-utils http://rpms.remirepo.net/enterprise/remi-release-9.rpm -y +```shell +sudo dnf install epel-release dnf-utils http://rpms.remirepo.net/enterprise/remi-release-9.rpm -y +``` Update/Upgrade system packages: - sudo dnf upgrade -y +```shell +sudo dnf upgrade -y +``` Now, install the latest version of Ansible: - sudo dnf install ansible -y +```shell +sudo dnf install ansible -y +``` Clone dotkernel/development into your home directory: - git clone https://github.com/dotkernel/development.git +```shell +git clone https://github.com/dotkernel/development.git +``` Move inside the directory `development/wsl`: - cd ~/development/wsl/ +```shell +cd ~/development/wsl/ +``` Using your preferred text editor, open `config.yml` where you must fill in the empty fields. @@ -68,7 +89,9 @@ Save and close the file. Install requirements and initialize systemd by running the below Ansible command: - ansible-playbook -i hosts install.yml --ask-become-pass +```shell +ansible-playbook -i hosts install.yml --ask-become-pass +``` The installation process will iterate over each task in the playbook and will output a short summary with the results. @@ -78,63 +101,84 @@ Open Windows Terminal. Stop AlmaLinux 9: - wsl -t AlmaLinux9 +```shell +wsl -t AlmaLinux9 +``` Start AlmaLinux 9: - wsl -d AlmaLinux9 +```shell +wsl -d AlmaLinux9 +``` Move inside the directory `development/wsl`: - cd ~/development/wsl/ +```cd ~/development/wsl/``` Continue installation by running the below Ansible command: - ansible-playbook -i hosts install.yml --ask-become-pass +```shell +ansible-playbook -i hosts install.yml --ask-become-pass +``` The installation process 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 development environment is ready to use. +- [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 development environment is ready to use. ## Create virtualhosts + Move inside the directory `development/wsl`: - cd ~/development/wsl/ +```shell +cd ~/development/wsl/ +``` -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. +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 ones will be skipped, no need to comment or remove them. ### NOTE -> 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. + +> 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. Save and close the file. Create the specified virtualhosts: - ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass +```shell +ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass +``` This will iterate over the list of configured `virtualhosts` and will 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`. +You will install your project under the `html` directory of your project, for example: +`/var/www/example.localhost/html`. ### NOTE -> The virtualhost's document root is set to the `public` directory of the above location, for example `/var/www/example.localhost/html/public`. +> 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` +> 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 -* In order 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](FAQ.md#how-do-i-fix-common-permission-issues). -* We install 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). -* We install NodeJS 22 by default. If you need a different version, see [this guide](FAQ.md#how-do-i-switch-to-a-different-version-of-nodejs). + +- In order 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](FAQ.md#how-do-i-fix-common-permission-issues). +- We install 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). +- We install NodeJS 22 by default. If you need a different version, see +[this guide](FAQ.md#how-do-i-switch-to-a-different-version-of-nodejs). diff --git a/wsl/os/almalinux9/roles/system/templates/bash_profile.j2 b/wsl/os/almalinux9/roles/system/templates/bash_profile.j2 index 24f04e4..9eb51bd 100644 --- a/wsl/os/almalinux9/roles/system/templates/bash_profile.j2 +++ b/wsl/os/almalinux9/roles/system/templates/bash_profile.j2 @@ -1,5 +1,6 @@ # PHP version switcher commands alias php74="sudo dnf module switch-to php:remi-7.4 -y" +alias php80="sudo dnf module switch-to php:remi-8.0 -y" alias php81="sudo dnf module switch-to php:remi-8.1 -y" alias php82="sudo dnf module switch-to php:remi-8.2 -y" alias php83="sudo dnf module switch-to php:remi-8.3 -y" diff --git a/wsl/os/ubuntu20/FAQ.md b/wsl/os/ubuntu20/FAQ.md index 569d539..6db4dab 100644 --- a/wsl/os/ubuntu20/FAQ.md +++ b/wsl/os/ubuntu20/FAQ.md @@ -1,96 +1,98 @@ # Frequently Asked Questions - ## How do I switch between PHP versions? + In this example we will switch from PHP version 7.4 to 8.1. Follow the same pattern if you need to switch between other versions than the ones presented in this example. Step 1: Disable PHP7.4: -``` + +```shell sudo a2dismod php7.4 ``` + Step 2: Enable PHP8.1: -``` + +```shell sudo a2enmod php8.1 ``` + Step 3: Make sure `php` points to PHP8.1: -``` + +```shell sudo update-alternatives --set php /usr/bin/php8.1 ``` + Step 4: Restart HTTP server: -``` + +```shell sudo service apache2 restart ``` - ## How do I switch to a different version of Node.js? ### Switch to Node.js 22.x - sudo apt remove nodejs -y - curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - - sudo apt install nodejs -y +```shell +sudo apt remove nodejs -y +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt install nodejs -y +``` ### Switch to Node.js 20.x - sudo apt remove nodejs -y - curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - - sudo apt install nodejs -y +```shell +sudo apt remove nodejs -y +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt install nodejs -y +``` ### Switch to Node.js 18.x - sudo apt remove nodejs -y - curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - - sudo apt install nodejs -y - -### Switch to Node.js 16.x - - sudo apt remove nodejs -y - curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - - sudo apt install nodejs -y - -### Switch to Node.js 14.x - - sudo apt remove nodejs -y - curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash - - sudo apt install nodejs -y - -### Switch to Node.js 12.x - - sudo apt remove nodejs -y - curl -fsSL https://deb.nodesource.com/setup_12.x | sudo -E bash - - sudo apt install nodejs -y +```shell +sudo apt remove nodejs -y +curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - +sudo apt install nodejs -y +``` -**Note**: Node.js 12.x is no longer actively supported! +## How do I fix common permission issues? +If running your project you encounter permission issues, follow the below steps. -## How do I fix common permission issues? -If running your project you encounter some permission issues, follow the below steps. +### Error -**Errors:** -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/home/_username_/projects/_example.local_/data" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data" is not writable... -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/home/_username_/projects/_example.local_/data/cache" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache" is not writable... -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/home/_username_/projects/_example.local_/data/cache/doctrine" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/data/cache/doctrine" is not +> writable... -**Fix:** +### Solution - chmod -R 777 data +```shell +chmod -R 777 data +``` +### Error -### Error: -> PHP Fatal error: Uncaught InvalidArgumentException: The directory "/home/_username_/projects/_example.local_/public/uploads" is not writable... +> PHP Fatal error: Uncaught InvalidArgumentException: The directory "``/public/uploads" is not +> writable... -**Fix:** +### Solution - chmod -R 777 public/uploads +```shell +chmod -R 777 public/uploads +``` +### Error -**Error:** -> PHP Fatal error: Uncaught ErrorException: fopen(/home/_username_/projects/_example.local_/config/autoload/../../log/error-log-_yyyy-mm-dd.log_): Failed to open stream: Permission denied... +> PHP Fatal error: Uncaught ErrorException: fopen(``/log/error-log-yyyy-mm-dd.log): Failed to open +> stream: Permission denied... -**Fix:** +### Solution - chmod -R 777 log +```shell +chmod -R 777 log +``` diff --git a/wsl/os/ubuntu20/README.md b/wsl/os/ubuntu20/README.md index 0f764d8..cf1f052 100644 --- a/wsl/os/ubuntu20/README.md +++ b/wsl/os/ubuntu20/README.md @@ -2,78 +2,99 @@ [< DotKernel: Install development environment](../../README.md) - ## Download Ubuntu 20 WSL image -Download Ubuntu 20 image by following one of the below methods. +Download `Ubuntu 20` image by following one of the below methods. ### Method 1: Download Ubuntu 20 WSL image using Windows Terminal -Open Windows Terminal and execute the following command: - wsl --install -d Ubuntu-20.04 +Open `Windows Terminal` and execute the following command: -You should see the download progress and once finished, the output should look like this: +```shell +wsl --install -d Ubuntu-20.04 +``` - Downloading: Ubuntu 20.04 LTS - Installing: Ubuntu 20.04 LTS - Ubuntu 20.04 LTS has been installed. - Launching Ubuntu 20.04 LTS... +You should see the download progress and once finished, the output should look like this: -Also, you should find a new tab in Windows Terminal that is already connected to Ubuntu 20. +```text +Downloading: Ubuntu 20.04 LTS +Installing: Ubuntu 20.04 LTS +Ubuntu 20.04 LTS has been installed. +Launching Ubuntu 20.04 LTS... +``` +Also, you should find a new tab in `Windows Terminal` that is already connected to Ubuntu 20. ### Method 2: Download Ubuntu 20 WSL image from Microsoft Store + Open Microsoft Store, in the search box type in: `Ubuntu` and hit `Enter`. From the results, select `Ubuntu 20.04.4 LTS` - this will take you to Ubuntu 20's app page. On this page, locate and click the `Install` button - this will download Ubuntu 20 WSL image on your machine. -Once the download has finished, the `Install` button is replaced by an `Open` button - clicking it will open Windows Terminal. - +Once the download has finished, the `Install` button is replaced by an `Open` button - clicking it will open +`Windows Terminal`. ## Install Ubuntu 20 + You will be asked to fill in your username (for example `dotkernel`): - 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: +```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): - Enter new UNIX username: dotkernel. - Changing password for user dotkernel. - New password: +```text +Enter new UNIX username: dotkernel. +Changing password for user dotkernel. +New password: +``` Next, you are asked to retype your password: - Retype new password: +```text +Retype new password: +``` Finally, you should see the following message: - passwd: password updated successfully - Installation successful! - ... - dotkernel@hostname:~$ - +```text +passwd: password updated successfully +Installation successful! +... +dotkernel@hostname:~$ +``` ## Install services on Ubuntu 20 + Update/Upgrade system packages: - sudo apt-get update && sudo apt-get upgrade -y +```shell +sudo apt-get update && sudo apt-get upgrade -y +``` Now, install the latest version of Ansible: - sudo apt-get install ansible -y +```shell +sudo apt-get install ansible -y +``` Clone dotkernel/development into your home directory: - git clone https://github.com/dotkernel/development.git +```shell +git clone https://github.com/dotkernel/development.git +``` Move inside the directory `development/wsl`: - cd ~/development/wsl/ +```shell +cd ~/development/wsl/ +``` Using your preferred text editor, open `config.yml` where you must fill in the empty fields. @@ -81,13 +102,15 @@ Save and close the file. Install and configure all necessary services by running the below Ansible command: - ansible-playbook -i hosts install.yml --ask-become-pass +```shell +ansible-playbook -i hosts install.yml --ask-become-pass +``` The installation process will iterate over each task in the playbook and will output a short summary with the results. -At this point, Ubuntu 20 needs to be restarted, so quit it by pressing `Control` + `d`. +At this point, `Ubuntu 20` needs to be restarted, so quit it by pressing `Control` + `d`. -Open Windows Terminal. +Open `Windows Terminal`. Stop Ubuntu 20: @@ -98,19 +121,24 @@ Start Ubuntu 20: wsl -d Ubuntu-20.04 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 development environment is ready to use. +- [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 development environment is ready to use. ## Create virtual hosts + Move inside the directory `development/wsl`: - cd ~/development/wsl/ +```shell +cd ~/development/wsl/ +``` -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. +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 ones will be skipped, no need to comment or remove them. @@ -118,19 +146,25 @@ Save and close the file. Create the specified virtualhosts: - ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass +```shell +ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass +``` This will iterate over the list of configured `virtualhosts` and will output a short summary with the results. Your virtualhost should be accessible and ready to use. You will install your projects under the `/home/your-username/projects/` directory. -The virtualhost's document root is set to the `public` directory of the above location, for example `/home/your-username/projects/example.local/public`. +The virtualhost's document root is set to the `public` directory of the above location, for example +`/home/your-username/projects/example.local/public`. **Note**: -* In order to run your installed projects, you need to start Ubuntu 20 first. -* If you work with virtualhosts, your projects are created under `/home/your-username/projects/`. -* 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](FAQ.md#how-do-i-fix-common-permission-issues). -* Default version of PHP is set to 8.3. If you need a different version, see [this guide](FAQ.md#how-do-i-switch-between-php-versions). -* We install NodeJS 22 by default. If you need a different version, see [this guide](FAQ.md#how-do-i-switch-to-a-different-version-of-nodejs). + +- In order to run your installed projects, you need to start Ubuntu 20 first. +- If you work with virtualhosts, your projects are created under `/home/your-username/projects/`. +- 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](FAQ.md#how-do-i-fix-common-permission-issues). +- Default version of PHP is set to 8.3. If you need a different version, see +[this guide](FAQ.md#how-do-i-switch-between-php-versions). +- We install NodeJS 22 by default. If you need a different version, see +[this guide](FAQ.md#how-do-i-switch-to-a-different-version-of-nodejs).