133 lines
6.2 KiB
Markdown
133 lines
6.2 KiB
Markdown
# 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`. |