Lenvi

The name Lenvi stands for Laravel, Legacy, and Lightweight Environment. 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 Laravel applications and complex Legacy PHP sites with ease, all while remaining incredibly Lightweight.

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

• Ubuntu 22.04 or higher (or WSL2 with Ubuntu).
• Ansible & Git: Must be installed on the machine.

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

• Sudo Access: Your user must have sudo privileges.

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/Lenvi.git ~/Lenvi && cd ~/Lenvi

2. Configure Your Environment (Lenvi.yaml)

This is the most important step. Open Lenvi.yaml and define your entire environment.

# ------------------------------------------------------------------
# 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"
  password: "secret"
# 3. Your Web Projects
sites:
  - domain: mylaravelapp.local
    project_root: /home/lenvi/projects/laravel
    document_root: /home/lenvi/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. 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):

chmod +x lenvi.sh

Now, run the script. It will handle everything for you and will prompt for your sudo password to perform the necessary system changes.

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

  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 Lenvi.yaml:

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 (.env)

Update your application's .env file to use the database credentials from Lenvi.yaml. Example .env for mylaravelapp.local:

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=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://mylaravelapp.local.
• Smart PHP Version: The php, composer, and artisan commands are context-aware.

  cd /home/lenvi/projects/laravel
  php --version # Will show the PHP version defined for this site
  composer install
  

Daily Workflow

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.