diff --git a/README.md b/README.md index 02e9b4d..d09c88a 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,29 @@ -# WSL2 development environment +# Development environment -This is a collection of Ansible scripts helping with the creation and maintenance of your WSL2 development environment. +This repo provisions a full local development environment for any PHP framework or project, using an Ansible playbook, runnable directly on Linux or inside WSL 2 on Windows. -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... +## What you get -## Check if WLS2 is already available +Running the playbook installs and configures: -Open `Windows Terminal` and execute the following command: +* Apache +* PHP-FPM (version pinned in `wsl/roles/php/tasks/main.yml`) +* MariaDB (version pinned in `wsl/roles/mariadb/templates/MariaDB.repo.j2`) +* phpMyAdmin +* Composer +* Node.js 22 -```shell -wsl -v -``` +## Which version should I use? -The output should look similar to this: +Two versions of this guide are maintained: -```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 -``` +* **v2** targets **AlmaLinux 10** and is the current, actively maintained version - start here unless you have a specific reason not to. +* **v1** targets **AlmaLinux 9**, for environments that haven't moved to AlmaLinux 10 yet. -If the output starts with `WSL version: 2.x.x.x`, you are ready to use **WSL2** and can proceed to [install AlmaLinux 10](wsl/README.md). +## Getting started -## Install WSL2 +Full documentation is published at . -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. +If you're using WSL 2 (Windows Subsystem for Linux) to run your development environment, start with [Terminal](https://docs.dotkernel.org/development/v2/terminal/) to install Windows Terminal, then continue to [System Requirements](https://docs.dotkernel.org/development/v2/setup/system-requirements/). -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 10](wsl/README.md). +If you're not using WSL (for example, a native Linux host), you can jump straight to [Setup Packages](https://docs.dotkernel.org/development/v2/setup/setup-packages/). diff --git a/wsl/README.md b/wsl/README.md index ed81777..14b3fc4 100644 --- a/wsl/README.md +++ b/wsl/README.md @@ -1,251 +1,6 @@ -# AlmaLinux 10 Installation +# WSL 2 development environment -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. +This folder contains the Ansible playbook used to provision a local development environment (Apache, PHP-FPM, MariaDB, phpMyAdmin, Composer, and Node.js). +It runs directly on Linux or via WSL 2 on Windows, and is designed for development in any PHP framework or project. -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-10) section. - -If you have other distros installed, the output could look similar to the below: - -```text - NAME STATE VERSION - AlmaLinux-8 Stopped 2 -* AlmaLinux-9 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-10) section. - -## Install AlmaLinux 10 - -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-10`. - -> If you try to install a distro that is already installed, the installation process will fail: - -```text -Downloading: AlmaLinux OS 10 -Installing: AlmaLinux OS 10 -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 10** 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 **AlmaLinux 10**, 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: ` 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. -[@ ]$ -``` - -## Setup AlmaLinux 10 - -Install system packages: - -```shell -sudo dnf install epel-release dnf-utils https://rpms.remirepo.net/enterprise/remi-release-10.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. - -For security reasons, the password you type will not be visible. - -[sudo] password for dotkernel: -``` - -Input your **AlmaLinux 10** password and hit `Enter`. - -Update/Upgrade system packages: - -```shell -sudo dnf upgrade -y -``` - -Now, install the latest version of **Ansible Core** and run **ansible-galaxy** to install collections: - -```shell -sudo dnf install ansible-core -y -``` - -```shell -ansible-galaxy collection install community.general community.mysql -``` - -Move inside your home directory (it is `/home/` followed by your **AlmaLinux 10** username, for example: `/home/dotkernel`): - -```shell -cd ~ -``` - -Clone the `alma-linux-10` branch of the `dotkernel/development` repository: - -```shell -git clone --branch alma-linux-10 --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 10** 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 10** development environment is ready to use. - -> Restart your `Windows Terminal` to find a new option in the tab selector, called **AlmaLinux-10**; clicking it will open a new tab connected to **AlmaLinux 10**. - -## 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 10** 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 10** 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/v2/faq/#how-do-i-fix-common-permission-issues). -* We install PHP 8.5 by default—if you need a different version, see [this guide](https://docs.dotkernel.org/development/v2/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/v2/faq/#how-do-i-switch-to-a-different-version-of-nodejs). +Full, up-to-date installation instructions: