# Lenverge Lenverge is a lightweight, Ansible-powered environment tool built for Laravel and legacy PHP projects. It delivers fast, VM-free provisioning directly on Ubuntu or WSL2 — ideal for modern apps and legacy codebases alike. > Lenverge comes from Laravel, Legacy, and Lightweight Environment — built for projects that sit on the verge of legacy and modern, and need a clean bridge. ### Core Features * **No Virtual Machine:** Runs directly on Ubuntu 22.04+ (or WSL2 Ubuntu). * **Centralized Configuration:** Define your entire stack in one simple `Lenverge.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 * **Ubuntu 22.04 or higher** (or WSL2 with Ubuntu). * **Sudo Access:** Your user must have `sudo` privileges. * **Core Dependencies:** You need Ansible, Git, and the Ansible collection for PostgreSQL management. You can install all of them with these two commands. **1. Install System Packages:** ```bash sudo apt update && sudo apt install ansible git -y ``` **2. Install Ansible PostgreSQL Collection:** ```bash ansible-galaxy collection install community.postgresql ``` ## How to Run ### 1. Get the Code Clone the repository to a convenient location, like your home directory. ```bash git clone https://git.marmattheo.com/marito/Lenverge.git ~/Lenverge && cd ~/Lenverge ``` ### 2. Configure Your Environment (`Lenverge.yaml`) This is the most important step. Open `Lenverge.yaml` and define your entire environment. ```yaml # ------------------------------------------------------------------ # Lenverge: Central Configuration for Your Development Environment # ------------------------------------------------------------------ # Optional developer utilities utilities: phpmyadmin: enabled: false domain: "pma.lenverge.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: "Lenverge" password: "secret" # 3. Your Web Projects sites: - domain: mylaravelapp.local project_root: /home/lenverge/projects/laravel document_root: /home/lenverge/projects/laravel/public php_version: "8.2" database: "laravel_db" ``` **Key Configuration Options:** * **`utilities`**: Set `enabled: true` to install optional tools like `phpmyadmin` and `redis`. * **`db_engine`**: Choose between `mariadb`, `mysql`, or `postgresql`. Lenverge 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 `lenverge.sh` script. First, make the script executable (you only need to do this once): ```bash chmod +x lenverge.sh ``` Now, run the script. It will handle everything for you and will prompt for your `sudo` password to perform the necessary system changes. ```bash ./lenverge.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 `./lenverge.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):** Open **Notepad as an Administrator** and edit `C:\Windows\System32\drivers\etc\hosts`. Add an entry for each domain defined in `Lenverge.yaml`: ``` 127.0.0.1 mylaravelapp.local # Add other project domains here # Add utility domains if enabled, e.g.: # 127.0.0.1 pma.lenverge.local ``` ### 2. Configure Your Application (`.env`) Update your application's `.env` file to use the database credentials from `Lenverge.yaml`. **Example `.env` for `mylaravelapp.local` (MariaDB/MySQL):** ```env DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=laravel_db DB_USERNAME=Lenverge DB_PASSWORD=secret # If you enabled Redis in Lenverge.yaml REDIS_HOST=127.0.0.1 REDIS_PASSWORD=null REDIS_PORT=6379 ``` **Example `.env` for a PostgreSQL project:** ```env DB_CONNECTION=pgsql DB_HOST=127.0.0.1 DB_PORT=5432 DB_DATABASE=laravel_db_pg DB_USERNAME=Lenverge DB_PASSWORD=secret ``` ### 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/lenverge/projects/laravel php --version # Will show the PHP version defined for this site composer install ``` ## Daily Workflow Lenverge is designed to be declarative. To make any changes, simply edit `Lenverge.yaml` and re-run the provisioning script with `./lenverge.sh`. * **To Add a New Site:** Add a new entry to the `sites` list, update your `hosts` file, and run `./lenverge.sh`. * **To Remove a Site:** Delete the site's block from `Lenverge.yaml`. When you re-run `./lenverge.sh`, Lenverge will automatically remove its Nginx configuration. * **To Change a PHP Version:** Update the `php_version` for a site and run `./lenverge.sh`. * **To Enable a Utility:** Set `enabled: true` for `phpmyadmin` or `redis`, update your `hosts` file if needed, and run `./lenverge.sh`.