From a97c8e77eb4f272f3b2e76479a0f50597548791b Mon Sep 17 00:00:00 2001 From: marito Date: Sun, 15 Jun 2025 08:21:15 +0800 Subject: [PATCH] readme updated --- README.md | 148 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 97 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 3f18629..bd0cc6b 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,100 @@ -# Lenvi Ansible Provisioner - -Lenvi is a lightweight, Ansible-powered tool for managing local Laravel development environments. It provides a Homestead-like experience without the overhead of a virtual machine, running natively on Linux or on Windows via WSL2. - +# 🧰 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 `lenvi.yaml` file. -- **Multi-PHP:** Assign a specific PHP version (e.g., 8.0, 8.2, 8.3) to each site. -- **Database Support:** Automatically creates databases using a shared MariaDB, MySQL, or PostgreSQL server. -- **Idempotent:** Safely run the provisioner at any time to update your environment. - -## Prerequisites - -1. **Ansible:** You must have Ansible installed. +- **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. +### 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`: +```bash +sudo apt update +sudo apt install software-properties-common +sudo add-apt-repository --yes --update ppa:ansible/ansible +sudo apt install 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. +**Example `Lenvi.yaml`:** +```yaml +# Set the global database engine. +db_engine: "mariadb" +# Define all your Laravel sites. +sites: + - domain: myapp.local + project_root: /home/mar/projects/myapp + php_version: "8.2" + - domain: legacy-app.local + 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. +```bash +cd /path/to/lenvi-ansible +ansible-playbook playbook.yml +``` +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: +```bash +sudo nano /etc/hosts +``` +Add an entry for each site you defined in `Lenvi.yaml`, pointing to your local IP address. +``` +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. +## Daily Workflow +Managing your environment is as simple as editing one file. +### 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. +### 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. +### Removing a Site +1. Delete the site's block from the `sites` list in `Lenvi.yaml`. +2. Manually delete the site's Nginx configuration file: ```bash - # On Debian/Ubuntu - sudo apt update - sudo apt install python3-pip -y - pip3 install ansible + # Example for myapp.local + sudo rm /etc/nginx/conf.d/myapp.local.conf ``` -2. **WSL2 (for Windows users):** Install WSL2 and a Linux distribution like **Ubuntu 22.04** from the Microsoft Store. All subsequent commands must be run from the WSL2 terminal. - -## How to Use - -1. **Clone this repository:** - ```bash - git clone ~/tools/lenvi_ansible - ``` - -2. **Configure `lenvi.yaml`:** - Open `~/tools/lenvi_ansible/lenvi.yaml` and configure it for your projects. Set your `db_engine` and list all your sites under the `sites` key. - -3. **Run the Playbook:** - Navigate to the `lenvi_ansible` directory and run the main playbook. - ```bash - cd ~/tools/lenvi_ansible - ansible-playbook playbook.yml --ask-become-pass - ``` - Ansible will ask for your `sudo` password to install software and configure services. - -### Important Note for Windows (WSL2) Users - -For your Windows browser (Chrome, Firefox, etc.) to access a site like `myapp.test`, you must manually edit the **Windows hosts file**. - -1. Open **Notepad** as an **Administrator**. -2. Open the file: `C:\Windows\System32\drivers\etc\hosts` -3. For each site in your `lenvi.yaml`, add a new line: - ``` - 127.0.0.1 myapp.test - 127.0.0.1 another-app.test - ``` -4. Save the file. You only need to do this once per new domain. - -You can now access your sites in your browser! \ No newline at end of file +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