Lenverge/README.md

Lenvi - Ansible-Powered Laravel Development Environment

This Ansible playbook automates the setup of a complete Laravel development environment directly on your local machine (Debian/Ubuntu/WSL2). It installs and configures Nginx, multiple PHP versions, and your choice of database based on a simple Lenvi.yaml configuration file.

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.
• Debian-based OS: A distribution like Ubuntu or Debian is required for apt and the Ondřej PPA for PHP. This includes WSL distributions.

How to Run

1. Get the Code

Clone the repository and enter the project directory.

git clone https://git.marmattheo.com/marito/Lenvi.git lenvi-ansible && cd lenvi-ansible

2. Configure Lenvi

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

• Set your global db_engine.
• Define all your projects under the sites list with their correct domain, project_root, and php_version. 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"

3. Execute 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).

🚀 Final Setup

After the playbook completes successfully, there is one final manual step.

Update Your Hosts File

For your browser to resolve local domains like myapp.local, you must map them to your machine's local IP address (127.0.0.1). The location of this file depends on your operating system.

On Linux (Desktop)

Edit the /etc/hosts file directly in your terminal:

sudo nano /etc/hosts

On Windows (for WSL Users)

If you are using WSL, you must edit the hosts file on Windows itself, not inside the Linux environment.

1. Open Notepad as an Administrator.
2. Click File -> Open and navigate to this path: C:\Windows\System32\drivers\etc\hosts
3. Add the entries to this file.

---

Example entries to add:

127.0.0.1   myapp.local
127.0.0.1   legacy-app.local

✅ You're all set! You can now access your sites, like http://myapp.local, in your browser.

Daily Workflow

Managing your environment is as simple as editing the Lenvi.yaml file and re-running the playbook.

Adding a New Site

1. Add a new project block to the sites list in Lenvi.yaml.
2. Add the new domain to your /etc/hosts file (or the Windows hosts file for WSL).
3. Re-run the playbook: ansible-playbook playbook.yml -i inventory --ask-become-pass

Changing a Site's PHP Version

1. In Lenvi.yaml, change the php_version for the desired site.
2. Re-run the playbook. Ansible will automatically install the new PHP version (if not already present) and update the Nginx configuration.

Removing a Site

1. Delete the project'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 to apply the changes and reload Nginx.
4. Remove the entry from your hosts file.