From a1c287fbfb7c659501e861f395a69d76e44bca94 Mon Sep 17 00:00:00 2001 From: marito Date: Mon, 16 Jun 2025 17:51:03 +0800 Subject: [PATCH] installer --- README.md | 183 +++++++++++++++++------------------- lenvi.sh | 29 ++++++ roles/common/tasks/main.yml | 9 +- 3 files changed, 121 insertions(+), 100 deletions(-) create mode 100644 lenvi.sh diff --git a/README.md b/README.md index 62c2099..7bf061f 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,116 @@ -# Lenvi: Laravel & Legacy Environment Simplified - -This setup is tailored for Laravel development but also supports legacy PHP apps. It provides a powerful, centralized environment with multi-PHP support on Ubuntu and WSL2 Ubuntu; similar to Homestead, but without the overhead of a virtual machine. Currently, it only works on Ubuntu 24.04 and above. -> WSL: Initial setup will stop for permission configuration reason, follow the instructions and run it properly again. - +# Lenvi +The name **Lenvi** stands for **L**aravel, **L**egacy, and **L**ightweight **Envi**ronment. +It's a fast, simple alternative to tools like Homestead or Laragon that uses Ansible to provision your local Ubuntu machine (or WSL2) directly, without the overhead of a virtual machine. True to its name, Lenvi is tailored to handle modern **L**aravel applications and complex **L**egacy PHP sites with ease, all while remaining incredibly **L**ightweight. +### Core Features +* **No Virtual Machine:** Runs directly on Ubuntu 22.04+ (or WSL2 Ubuntu). +* **Centralized Configuration:** Define your entire stack in one simple `Lenvi.yaml` file. +* **Multi-PHP Ready:** Run different sites on different PHP versions simultaneously. +* **Smart CLI Wrappers:** Automatically uses the correct PHP version for `php`, `composer`, and `artisan` commands based on your current project directory. +* **Developer Utilities:** Easily enable tools like phpMyAdmin and Redis. +* **WSL-Optimized:** Automatically configures WSL for optimal performance and file permissions. ## Prerequisites - -- **Ansible & Git:** Must be installed on the machine where you are running the playbook. - +* **Ubuntu 22.04 or higher** (or WSL2 with Ubuntu). +* **Ansible & Git:** Must be installed on the machine. ```bash sudo apt update && sudo apt install ansible git -y ``` - -- **Sudo Access:** Your user must have `sudo` privileges to run the playbook. - +* **Sudo Access:** Your user must have `sudo` privileges. ## How to Run - -### 1\. Setup: Get the Code - -Clone the repository and go to the project directory. - +### 1. Get the Code +Clone the repository to a convenient location, like your home directory. ```bash git clone https://git.marmattheo.com/marito/Lenvi.git ~/Lenvi && cd ~/Lenvi ``` - -### 2\. Configure: Define Your Projects - -This is the most important step. Open the `Lenvi.yaml` file and define your entire environment. - -- `project_root`: The base directory of your project. This is where you would run `git` or `composer` commands. -- `document_root`: The directory that Nginx will serve files from. For Laravel, this is the `public` sub-directory. -- `wsl disclaimer:` Project folders that does not live on wsl filesystem will be noticeably slower compared to the projects that lives directly wsl filesystem. i.e., /mnt/c/Users/user/projects/laravel-app -> This is slow. /home/user/projects/laravel-app -> Very Fast! - -**Example** `Lenvi.yaml`**:** - +### 2. Configure Your Environment (`Lenvi.yaml`) +This is the most important step. Open `Lenvi.yaml` and define your entire environment. ```yaml -db_engine: "mariadb" #mariadb, mysql or postgresql +# ------------------------------------------------------------------ +# Lenvi: Central Configuration for Your Development Environment +# ------------------------------------------------------------------ +# Optional developer utilities +utilities: + phpmyadmin: + enabled: false + domain: "pma.lenvi.local" + php_version: "8.2" + redis: + enabled: false +# 1. Database Engine: mariadb, mysql, or postgresql +db_engine: "mariadb" +# 2. Global Database Credentials db_credentials: -  user: "Lenvi" + user: "Lenvi" password: "secret" - +# 3. Your Web Projects sites: - - domain: local-api.laravel.com - project_root: /home/user/projects/my-laravel-app - document_root: /home/user/projects/my-laravel-app/public + - domain: mylaravelapp.local + project_root: /home/lenvi/projects/laravel + document_root: /home/lenvi/projects/laravel/public php_version: "8.2" database: "laravel_db" - - - domain: local.phpmyadmin.com - project_root: /home/user/projects/phpmyadmin - document_root: /home/user/projects/phpmyadmin - php_version: "8.3" # Required for Nginx config ``` - -### 3\. Execute: Run the Playbook - -Run the following command from the `lenvi-ansible` directory. It will prompt you for your `sudo` password to perform the administrative tasks. - +**Key Configuration Options:** +* **`utilities`**: Set `enabled: true` to install optional tools like `phpmyadmin` and `redis`. +* **`db_engine`**: Choose between `mariadb`, `mysql`, or `postgresql`. Lenvi will install and manage the correct service. +* **`sites`**: A list of all your projects. + * `domain`: The local domain name you'll use in the browser. + * `project_root`: The base directory of your project (where `.git` or `composer.json` lives). + * `document_root`: The public-facing directory Nginx serves (e.g., `/public` for Laravel). + * `php_version`: The PHP version for this specific site. + * `database`: (Optional) The name of the database to create for this site. +> **WSL Performance Tip:** For the best performance, keep your project files inside the WSL filesystem (e.g., `/home/user/projects`) rather than on the mounted Windows filesystem (e.g., `/mnt/c/Users/...`). +### 3. Run the Provisioning Script +To set up or update your environment, use the simple `lenvi.sh` script. +First, make the script executable (you only need to do this once): ```bash -ansible-playbook playbook.yml -i inventory --ask-become-pass +chmod +x lenvi.sh ``` - -> **\--ask-become-pass:** This flag tells Ansible to prompt for the password needed for privilege escalation (`sudo`). - -## Post-Installation Steps - -After the playbook completes successfully, follow these steps to start using your environment. - -### 1\. Finalize Host Access - -For your browser to resolve local domains like `my-laravel-app.local`, you must map them to `127.0.0.1`. - -- **On Linux:** - +Now, run the script. It will handle everything for you and will prompt for your `sudo` password to perform the necessary system changes. +```bash +./lenvi.sh +``` +> **WSL Users:** The very first time you run this, the script may stop and ask you to restart WSL. This is a one-time setup step to fix file permissions. Follow the on-screen instructions, and then re-run `./lenvi.sh`. +## Post-Installation +### 1. Update Your `hosts` File +For your browser to access local domains, you must map them to your local machine. +* **On Linux:** Edit `/etc/hosts`. ```bash sudo nano /etc/hosts ``` - -- **On Windows (for WSL Users):** - Open **Notepad** as an **Administrator** and edit the file `C:\Windows\System32\drivers\etc\hosts`. - **Add entries for each of your sites:** - +* **On Windows (for WSL):** Open **Notepad as an Administrator** and edit `C:\Windows\System32\drivers\etc\hosts`. +Add an entry for each domain defined in `Lenvi.yaml`: ``` -127.0.0.1 local-api.laravel.com -127.0.0.1 local.phpmyadmin.com +127.0.0.1 mylaravelapp.local +# Add other project domains here +# Add utility domains if enabled, e.g.: +# 127.0.0.1 pma.lenvi.local ``` - -### 2\. Configure Your Application - -Update your application's `.env` file to connect to the database. Use the global credentials and the specific database name you defined in `Lenvi.yaml`. -**Example** `.env` **for** `my-laravel-app.local`**:** - +### 2. Configure Your Application (`.env`) +Update your application's `.env` file to use the database credentials from `Lenvi.yaml`. +**Example `.env` for `mylaravelapp.local`:** ```env -DB_CONNECTION=mysql +DB_CONNECTION=mysql # Works for both mysql and mariadb DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=laravel_db -DB_USERNAME=lenvi -DB_PASSWORD=password +DB_USERNAME=Lenvi +DB_PASSWORD=secret +# If you enabled Redis in Lenvi.yaml +REDIS_HOST=127.0.0.1 +REDIS_PASSWORD=null +REDIS_PORT=6379 ``` - -### 3\. Verify Your Setup - -- **Web Access:** Open your browser and navigate to `http://my-laravel-app.local`. You should see your application. -- **Composer:** `cd` into your project's `project_root` and run `composer --version`. The "smart" wrapper will automatically use the correct PHP version for that project. - +### 3. Verify Your Setup +* **Web Access:** Open your browser and navigate to `http://mylaravelapp.local`. +* **Smart PHP Version:** The `php`, `composer`, and `artisan` commands are context-aware. ```bash - cd /home/user/projects/my-laravel-app + cd /home/lenvi/projects/laravel + php --version # Will show the PHP version defined for this site composer install ``` - ## Daily Workflow - -### Adding a New Site - -1. Add a new project block to the `sites` list in `Lenvi.yaml`. -2. Add the new domain to your hosts file. -3. Re-run the playbook. - -### Changing a Site's PHP Version - -1. In `Lenvi.yaml`, change the `php_version` for the desired site. -2. Re-run the playbook. - -### Removing a Site - -1. Delete the project's block from `Lenvi.yaml`. -2. Manually delete the site's Nginx configuration file (e.g., `sudo rm /etc/nginx/conf.d/local-api.laravel.com.conf`). -3. Re-run the playbook and remove the entry from your hosts file. \ No newline at end of file +Lenvi is designed to be declarative. To make any changes, simply edit `Lenvi.yaml` and re-run the provisioning script with `./lenvi.sh`. +* **To Add a New Site:** Add a new entry to the `sites` list, update your `hosts` file, and run `./lenvi.sh`. +* **To Remove a Site:** Delete the site's block from `Lenvi.yaml`. When you re-run `./lenvi.sh`, Lenvi will automatically remove its Nginx configuration. +* **To Change a PHP Version:** Update the `php_version` for a site and run `./lenvi.sh`. +* **To Enable a Utility:** Set `enabled: true` for `phpmyadmin` or `redis`, update your `hosts` file if needed, and run `./lenvi.sh`. \ No newline at end of file diff --git a/lenvi.sh b/lenvi.sh new file mode 100644 index 0000000..5a7c603 --- /dev/null +++ b/lenvi.sh @@ -0,0 +1,29 @@ +#!/bin/bash + +# --- Lenvi Provisioning Script --- +# This script simplifies running the Ansible playbook, making it accessible +# for users who are not familiar with Ansible. + +# Find the script's own directory to run from the correct location, +# ensuring that playbook.yml and other files are found. +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) +cd "$SCRIPT_DIR" + +echo "▶️ Starting Lenvi Provisioning..." +echo " This will install/update services based on your Lenvi.yaml configuration." +echo " You will be prompted for your sudo password to make system changes." +echo "" + +# Execute the Ansible playbook. +# The `if` statement checks the command's exit code to provide a clear success/failure message. +if ansible-playbook playbook.yml -i inventory --ask-become-pass; then + echo "" + echo "✅ Success! Your Lenvi environment has been provisioned." + echo " Don't forget to update your hosts file if you added or changed site domains." + echo "" +else + echo "" + echo "❌ Error: Lenvi provisioning failed." >&2 + echo " Please review the Ansible output above to diagnose the issue." >&2 + exit 1 +fi \ No newline at end of file diff --git a/roles/common/tasks/main.yml b/roles/common/tasks/main.yml index 76547cc..940bcb1 100644 --- a/roles/common/tasks/main.yml +++ b/roles/common/tasks/main.yml @@ -44,9 +44,14 @@ register: wsl_conf_result when: is_wsl | default(false) -- name: "STOP PLAYBOOK: Force user to restart WSL if wsl.conf was changed" +- name: Ensure /home/{{ ansible_user_id }} is executable by all (chmod +x) + ansible.builtin.file: + path: "/home/{{ ansible_user_id }}" + mode: '0711' + +- name: "FOR WSL USER: This error is safe and intentional. Follow instructions below." ansible.builtin.fail: msg: | - 🛑 ACTION REQUIRED: WSL Configuration Was Updated! The playbook has configured /etc/wsl.conf to fix file permissions. You MUST restart WSL for this change to take effect. The playbook has been stopped. Please perform the following steps: 1. Close this terminal. 2. Open Windows PowerShell or CMD (not as admin). 3. Run the command: wsl --shutdown 4. Wait a few seconds, then re-open your WSL terminal and cd ~/Lenvi. 5. Re-run the Lenvi playbook: ansible-playbook playbook.yml -i inventory --ask-become-pass After restarting, your file permission issues will be permanently solved. + ✅ ACTION REQUIRED: WSL Configuration was Updated! Lenvi has configured /etc/wsl.conf to fix file permissions. You MUST restart WSL for this change to take effect. Please perform the following steps: 1. Close this terminal. 2. Open Windows PowerShell or CMD (not as admin). 3. Run the command: wsl --shutdown 4. Wait a few seconds, then re-open your WSL terminal and cd ~/Lenvi. 5. Re-run ./lenvi.sh when: wsl_conf_result.changed \ No newline at end of file