Lenvi: Laravel & Legacy Environment Simplified

This setup is tailored for Laravel development but also supports legacy PHP apps. It provides a powerful, centralized environment with multi-PHP support on Ubuntu and WSL2 Ubuntu; similar to Homestead, but without the overhead of a virtual machine. Currently, it only works on Ubuntu 24.04 and above.

WSL: Initial setup will stop for permission configuration reason, follow the instructions and run it properly again.

Prerequisites

Ansible & Git: Must be installed on the machine where you are running the playbook.
```
sudo apt update && sudo apt install ansible git -y
```
Sudo Access: Your user must have sudo privileges to run the playbook.

How to Run

1. Setup: Get the Code

Clone the repository and go to the project directory.

git clone https://git.marmattheo.com/marito/Lenvi.git ~/Lenvi && cd ~/Lenvi

2. Configure: Define Your Projects

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

project_root: The base directory of your project. This is where you would run git or composer commands.
document_root: The directory that Nginx will serve files from. For Laravel, this is the public sub-directory.
wsl disclaimer: Project folders that does not live on linux filesystem will be noticeably slower compared to the projects that lives directly wsl filesystem. i.e., /mnt/c/Users/user/projects/laravel-app -> this is slow Example Lenvi.yaml:

db_engine: "mariadb" #mariadb, mysql or postgresql
db_credentials:
  user: "Lenvi"
  password: "secret"

sites:
  - domain: local-api.laravel.com
    project_root: /home/user/projects/my-laravel-app
    document_root: /home/user/projects/my-laravel-app/public
    php_version: "8.2"
    database: "laravel_db"

  - domain: local.phpmyadmin.com
    project_root: /home/user/projects/phpmyadmin
    document_root: /home/user/projects/phpmyadmin
    php_version: "8.3" # Required for Nginx config

3. Execute: Run the Playbook

Run the following command from the lenvi-ansible directory. It will prompt you for your sudo password to perform the administrative tasks.

ansible-playbook playbook.yml -i inventory --ask-become-pass

--ask-become-pass: This flag tells Ansible to prompt for the password needed for privilege escalation (sudo).

Post-Installation Steps

After the playbook completes successfully, follow these steps to start using your environment.

1. Finalize Host Access

For your browser to resolve local domains like my-laravel-app.local, you must map them to 127.0.0.1.

On Linux:
```
sudo nano /etc/hosts
```
On Windows (for WSL Users):
Open Notepad as an Administrator and edit the file C:\Windows\System32\drivers\etc\hosts.
Add entries for each of your sites:

127.0.0.1   local-api.laravel.com
127.0.0.1   local.phpmyadmin.com

2. Configure Your Application

Update your application's .env file to connect to the database. Use the global credentials and the specific database name you defined in Lenvi.yaml.
Example .env for my-laravel-app.local:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_db
DB_USERNAME=lenvi
DB_PASSWORD=password

3. Verify Your Setup

Web Access: Open your browser and navigate to http://my-laravel-app.local. You should see your application.
Composer: cd into your project's project_root and run composer --version. The "smart" wrapper will automatically use the correct PHP version for that project.
```
cd /home/user/projects/my-laravel-app
composer install
```

Daily Workflow

Adding a New Site

Add a new project block to the sites list in Lenvi.yaml.
Add the new domain to your hosts file.
Re-run the playbook.

Changing a Site's PHP Version

In Lenvi.yaml, change the php_version for the desired site.
Re-run the playbook.

Removing a Site

Delete the project's block from Lenvi.yaml.
Manually delete the site's Nginx configuration file (e.g., sudo rm /etc/nginx/conf.d/local-api.laravel.com.conf).
Re-run the playbook and remove the entry from your hosts file.