From 78e7d279ea5a0501d33e0cd21e21c777c74d39ea Mon Sep 17 00:00:00 2001 From: marito Date: Sun, 15 Jun 2025 08:27:24 +0800 Subject: [PATCH] readability --- README.md | 108 ++++++++++++++++++++++-------------------------------- 1 file changed, 43 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index bd0cc6b..a0b2eb0 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,22 @@ -# 🧰 Lenvi - Ansible-Powered Laravel Development Environment -Lenvi is a lightweight, configuration-driven development environment for Laravel, powered by Ansible. It's designed to be a simpler, more transparent alternative to virtual machines like Homestead or Docker setups like Sail, running directly on your local Linux machine (or WSL2). -The core idea is simple: define all your projects in a single `Lenvi.yaml` file, and let Ansible handle the rest. -## Features -- **Centralized Configuration**: Manage all your projects from a single, clean `Lenvi.yaml` file. -- **Multiple PHP Versions**: Run different projects with different PHP versions (e.g., 8.0, 8.2, 8.3) side-by-side. -- **Automatic Nginx Setup**: Generates a robust, secure, and performant Nginx configuration for each site automatically. -- **Choice of Database**: Easily install MariaDB, MySQL, or PostgreSQL for your environment. -- **Idempotent**: Re-running the playbook only applies necessary changes, making updates fast and safe. -- **Transparent**: No black boxes. You have full control over all configuration files and installed services. -## Requirements -- **OS**: An Ubuntu/Debian-based Linux distribution (e.g., Ubuntu 20.04/22.04 LTS). This is required for `apt` and the OndΕ™ej PPA for PHP. -- **Ansible**: Ansible must be installed on your machine. -- **Permissions**: You will need `sudo` access to run the playbook, as it installs software and modifies system configurations. -## Directory Structure -Your project should be structured as follows: -``` -lenvi-ansible/ -β”œβ”€β”€ ansible.cfg -β”œβ”€β”€ inventory -β”œβ”€β”€ Lenvi.yaml <-- YOU WILL EDIT THIS FILE -β”œβ”€β”€ playbook.yml -β”œβ”€β”€ README.md -└── roles/ - β”œβ”€β”€ common/ - β”œβ”€β”€ database/ - β”œβ”€β”€ nginx/ - β”œβ”€β”€ php/ - └── projects/ -``` -## Installation & Setup -Follow these steps to get your Lenvi environment up and running. +# Lenvi - Ansible-Powered Laravel Development Environment +This Ansible playbook automates the setup of a complete Laravel development environment directly on your local machine (Debian/Ubuntu/WSL2). It installs and configures Nginx, multiple PHP versions, and your choice of database based on a simple `Lenvi.yaml` configuration file. +## Prerequisites +- **Ansible & Git:** Must be installed on the machine where you are running the playbook. + ```bash + sudo apt update && sudo apt install ansible git -y + ``` +- **Sudo Access:** Your user must have `sudo` privileges to run the playbook. +- **Debian-based OS:** A distribution like Ubuntu or Debian is required for `apt` and the OndΕ™ej PPA for PHP. This includes WSL distributions. +## How to Run ### 1. Get the Code -Clone this repository or download and extract the files to a directory on your machine, for example `~/lenvi-ansible`. -### 2. Install Ansible -If you don't have Ansible installed, you can install it via `apt`: +Clone the repository and enter the project directory. ```bash -sudo apt update -sudo apt install software-properties-common -sudo add-apt-repository --yes --update ppa:ansible/ansible -sudo apt install ansible +git clone https://git.marmattheo.com/marito/Lenvi.git lenvi-ansible && cd lenvi-ansible ``` -### 3. Configure Your Environment -This is the most important step. Open the `Lenvi.yaml` file and customize it for your needs. -- Set the `db_engine` to your preferred database (`mariadb`, `mysql`, or `postgres`). -- Update the `sites` list to map your local project domains and their absolute paths. +### 2. Configure Lenvi +This is the most important step. Open the **`Lenvi.yaml`** file and customize it for your needs: +- Set your global `db_engine`. +- Define all your projects under the `sites` list with their correct `domain`, `project_root`, and `php_version`. **Example `Lenvi.yaml`:** ```yaml # Set the global database engine. @@ -57,44 +30,49 @@ sites: project_root: /home/mar/projects/legacy-app php_version: "8.0" ``` -### 4. Run the Playbook -Navigate to the `lenvi-ansible` directory in your terminal and execute the main playbook. Ansible will ask for your `sudo` password to perform administrative tasks. +### 3. Execute the Playbook +Run the following command from the `lenvi-ansible` directory. It will prompt you for your `sudo` password to perform the administrative tasks. ```bash -cd /path/to/lenvi-ansible -ansible-playbook playbook.yml +ansible-playbook playbook.yml -i inventory --ask-become-pass ``` -Ansible will now: -- Add the PPA for PHP. -- Install all required PHP versions. -- Install Nginx and your chosen database. -- Generate and place an Nginx config for each site into `/etc/nginx/conf.d/`. -- Reload services. -### 5. Update Your Hosts File -For your browser to resolve domains like `myapp.local`, you must map them to your local machine. Edit your `/etc/hosts` file: +> **--ask-become-pass:** This flag tells Ansible to prompt for the password needed for privilege escalation (`sudo`). +## πŸš€ Final Setup +After the playbook completes successfully, there is one final manual step. +### Update Your Hosts File +For your browser to resolve local domains like `myapp.local`, you must map them to your machine's local IP address (`127.0.0.1`). The location of this file depends on your operating system. +#### On Linux (Desktop) +Edit the `/etc/hosts` file directly in your terminal: ```bash sudo nano /etc/hosts ``` -Add an entry for each site you defined in `Lenvi.yaml`, pointing to your local IP address. +#### On Windows (for WSL Users) +If you are using WSL, you **must** edit the hosts file on Windows itself, not inside the Linux environment. +1. Open **Notepad** as an **Administrator**. +2. Click `File -> Open` and navigate to this path: + `C:\Windows\System32\drivers\etc\hosts` +3. Add the entries to this file. +--- +**Example entries to add:** ``` 127.0.0.1 myapp.local 127.0.0.1 legacy-app.local ``` -**That's it!** You can now access `http://myapp.local` and `http://legacy-app.local` in your browser. +βœ… **You're all set!** You can now access your sites, like `http://myapp.local`, in your browser. ## Daily Workflow -Managing your environment is as simple as editing one file. +Managing your environment is as simple as editing the `Lenvi.yaml` file and re-running the playbook. ### Adding a New Site -1. Add a new block to the `sites` list in `Lenvi.yaml`. -2. Re-run the playbook: `ansible-playbook playbook.yml`. -3. Add the new domain to your `/etc/hosts` file. +1. Add a new project block to the `sites` list in `Lenvi.yaml`. +2. Add the new domain to your `/etc/hosts` file (or the Windows hosts file for WSL). +3. Re-run the playbook: `ansible-playbook playbook.yml -i inventory --ask-become-pass` ### Changing a Site's PHP Version 1. In `Lenvi.yaml`, change the `php_version` for the desired site. -2. Re-run the playbook: `ansible-playbook playbook.yml`. Ansible will install the new PHP version if needed and update the Nginx config. +2. Re-run the playbook. Ansible will automatically install the new PHP version (if not already present) and update the Nginx configuration. ### Removing a Site -1. Delete the site's block from the `sites` list in `Lenvi.yaml`. +1. Delete the project's block from the `sites` list in `Lenvi.yaml`. 2. Manually delete the site's Nginx configuration file: ```bash # Example for myapp.local sudo rm /etc/nginx/conf.d/myapp.local.conf ``` -3. Re-run the playbook (`ansible-playbook playbook.yml`) to reload Nginx with the updated configuration. -4. Remove the entry from your `/etc/hosts` file. \ No newline at end of file +3. Re-run the playbook to apply the changes and reload Nginx. +4. Remove the entry from your hosts file. \ No newline at end of file