Lenverge/README.md

🧰 Lenvi - Ansible-Powered Laravel Development Environment

Lenvi is a lightweight, configuration-driven development environment for Laravel, powered by Ansible. It's designed to be a simpler, more transparent alternative to virtual machines like Homestead or Docker setups like Sail, running directly on your local Linux machine (or WSL2). The core idea is simple: define all your projects in a single Lenvi.yaml file, and let Ansible handle the rest.

Features

• Centralized Configuration: Manage all your projects from a single, clean Lenvi.yaml file.
• Multiple PHP Versions: Run different projects with different PHP versions (e.g., 8.0, 8.2, 8.3) side-by-side.
• Automatic Nginx Setup: Generates a robust, secure, and performant Nginx configuration for each site automatically.
• Choice of Database: Easily install MariaDB, MySQL, or PostgreSQL for your environment.
• Idempotent: Re-running the playbook only applies necessary changes, making updates fast and safe.
• Transparent: No black boxes. You have full control over all configuration files and installed services.

Requirements

• OS: An Ubuntu/Debian-based Linux distribution (e.g., Ubuntu 20.04/22.04 LTS). This is required for apt and the Ondřej PPA for PHP.
• Ansible: Ansible must be installed on your machine.
• Permissions: You will need sudo access to run the playbook, as it installs software and modifies system configurations.

Directory Structure

Your project should be structured as follows:

lenvi-ansible/
├── ansible.cfg
├── inventory
├── Lenvi.yaml         <-- YOU WILL EDIT THIS FILE
├── playbook.yml
├── README.md
└── roles/
    ├── common/
    ├── database/
    ├── nginx/
    ├── php/
    └── projects/

Installation & Setup

Follow these steps to get your Lenvi environment up and running.

1. Get the Code

Clone this repository or download and extract the files to a directory on your machine, for example ~/lenvi-ansible.

2. Install Ansible

If you don't have Ansible installed, you can install it via apt:

sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install ansible

3. Configure Your Environment

This is the most important step. Open the Lenvi.yaml file and customize it for your needs.

• Set the db_engine to your preferred database (mariadb, mysql, or postgres).
• Update the sites list to map your local project domains and their absolute paths. Example Lenvi.yaml:

# Set the global database engine.
db_engine: "mariadb"
# Define all your Laravel sites.
sites:
  - domain: myapp.local
    project_root: /home/mar/projects/myapp
    php_version: "8.2"
  - domain: legacy-app.local
    project_root: /home/mar/projects/legacy-app
    php_version: "8.0"

4. Run the Playbook

Navigate to the lenvi-ansible directory in your terminal and execute the main playbook. Ansible will ask for your sudo password to perform administrative tasks.

cd /path/to/lenvi-ansible
ansible-playbook playbook.yml

Ansible will now:

• Add the PPA for PHP.
• Install all required PHP versions.
• Install Nginx and your chosen database.
• Generate and place an Nginx config for each site into /etc/nginx/conf.d/.
• Reload services.

5. Update Your Hosts File

For your browser to resolve domains like myapp.local, you must map them to your local machine. Edit your /etc/hosts file:

sudo nano /etc/hosts

Add an entry for each site you defined in Lenvi.yaml, pointing to your local IP address.

127.0.0.1   myapp.local
127.0.0.1   legacy-app.local

That's it! You can now access http://myapp.local and http://legacy-app.local in your browser.

Daily Workflow

Managing your environment is as simple as editing one file.

Adding a New Site

1. Add a new block to the sites list in Lenvi.yaml.
2. Re-run the playbook: ansible-playbook playbook.yml.
3. Add the new domain to your /etc/hosts file.

Changing a Site's PHP Version

1. In Lenvi.yaml, change the php_version for the desired site.
2. Re-run the playbook: ansible-playbook playbook.yml. Ansible will install the new PHP version if needed and update the Nginx config.

Removing a Site

1. Delete the site's block from the sites list in Lenvi.yaml.
2. Manually delete the site's Nginx configuration file:

   # Example for myapp.local
   sudo rm /etc/nginx/conf.d/myapp.local.conf
   

3. Re-run the playbook (ansible-playbook playbook.yml) to reload Nginx with the updated configuration.
4. Remove the entry from your /etc/hosts file.