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:

  sudo apt update && sudo apt install ansible git -y
  

  2. Install Ansible PostgreSQL Collection:

  ansible-galaxy collection install community.postgresql
  

How to Run

1. Get the Code

Clone the repository to a convenient location, like your home directory.

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.

# ------------------------------------------------------------------
# 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):

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.

./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.

  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):

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:

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.

  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.