Lenvi

The name Lenvi stands for Laravel, Legacy, and Lightweight Environment. It's a fast, simple alternative to tools like Homestead 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).
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/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 (MariaDB/MySQL):

DB_CONNECTION=mysql
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

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

6.1 KiB Raw Blame History