marito/Lenverge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readability

Browse Source
This commit is contained in:
marito 2025-06-15 08:27:24 +08:00
parent a97c8e77eb
commit 78e7d279ea
1 changed files with 43 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@ -1,49 +1,22 @@
# 🧰 Lenvi - Ansible-Powered Laravel Development Environment # 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). 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.
The core idea is simple: define all your projects in a single `Lenvi.yaml` file, and let Ansible handle the rest. ## Prerequisites
## Features - **Ansible & Git:** Must be installed on the machine where you are running the playbook.
- **Centralized Configuration**: Manage all your projects from a single, clean `Lenvi.yaml` file. ```bash
- **Multiple PHP Versions**: Run different projects with different PHP versions (e.g., 8.0, 8.2, 8.3) side-by-side. sudo apt update && sudo apt install ansible git -y
- **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. - **Sudo Access:** Your user must have `sudo` privileges to run the playbook.
- **Idempotent**: Re-running the playbook only applies necessary changes, making updates fast and safe. - **Debian-based OS:** A distribution like Ubuntu or Debian is required for `apt` and the Ondřej PPA for PHP. This includes WSL distributions.
- **Transparent**: No black boxes. You have full control over all configuration files and installed services. ## How to Run
## 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 ### 1. Get the Code
Clone this repository or download and extract the files to a directory on your machine, for example `~/lenvi-ansible`. Clone the repository and enter the project directory.
### 2. Install Ansible
If you don't have Ansible installed, you can install it via `apt`:
```bash ```bash
sudo apt update git clone https://git.marmattheo.com/marito/Lenvi.git lenvi-ansible && cd lenvi-ansible
sudo apt install software-properties-common
sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install ansible
``` ```
### 3. Configure Your Environment ### 2. Configure Lenvi
This is the most important step. Open the `Lenvi.yaml` file and customize it for your needs. 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`). - Set your global `db_engine`.
- Update the `sites` list to map your local project domains and their absolute paths. - Define all your projects under the `sites` list with their correct `domain`, `project_root`, and `php_version`.
**Example `Lenvi.yaml`:** **Example `Lenvi.yaml`:**
```yaml ```yaml
# Set the global database engine. # Set the global database engine.
@ -57,44 +30,49 @@ sites:
project_root: /home/mar/projects/legacy-app project_root: /home/mar/projects/legacy-app
php_version: "8.0" php_version: "8.0"
``` ```
### 4. Run the Playbook ### 3. Execute 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. Run the following command from the `lenvi-ansible` directory. It will prompt you for your `sudo` password to perform the administrative tasks.
```bash ```bash
cd /path/to/lenvi-ansible ansible-playbook playbook.yml -i inventory --ask-become-pass
ansible-playbook playbook.yml
``` ```
Ansible will now: > **--ask-become-pass:** This flag tells Ansible to prompt for the password needed for privilege escalation (`sudo`).
- Add the PPA for PHP. ## 🚀 Final Setup
- Install all required PHP versions. After the playbook completes successfully, there is one final manual step.
- Install Nginx and your chosen database. ### Update Your Hosts File
- Generate and place an Nginx config for each site into `/etc/nginx/conf.d/`. 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.
- Reload services. #### On Linux (Desktop)
### 5. Update Your Hosts File Edit the `/etc/hosts` file directly in your terminal:
For your browser to resolve domains like `myapp.local`, you must map them to your local machine. Edit your `/etc/hosts` file:
```bash ```bash
sudo nano /etc/hosts sudo nano /etc/hosts
``` ```
Add an entry for each site you defined in `Lenvi.yaml`, pointing to your local IP address. #### 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 myapp.local
127.0.0.1 legacy-app.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. ✅ **You're all set!** You can now access your sites, like `http://myapp.local`, in your browser.
## Daily Workflow ## Daily Workflow
Managing your environment is as simple as editing one file. Managing your environment is as simple as editing the `Lenvi.yaml` file and re-running the playbook.
### Adding a New Site ### Adding a New Site
1. Add a new block to the `sites` list in `Lenvi.yaml`. 1. Add a new project block to the `sites` list in `Lenvi.yaml`.
2. Re-run the playbook: `ansible-playbook playbook.yml`. 2. Add the new domain to your `/etc/hosts` file (or the Windows hosts file for WSL).
3. Add the new domain to your `/etc/hosts` file. 3. Re-run the playbook: `ansible-playbook playbook.yml -i inventory --ask-become-pass`
### Changing a Site's PHP Version ### Changing a Site's PHP Version
1. In `Lenvi.yaml`, change the `php_version` for the desired site. 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. 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 ### Removing a Site
1. Delete the site's block from the `sites` list in `Lenvi.yaml`. 1. Delete the project's block from the `sites` list in `Lenvi.yaml`.
2. Manually delete the site's Nginx configuration file: 2. Manually delete the site's Nginx configuration file:
```bash ```bash
# Example for myapp.local # Example for myapp.local
sudo rm /etc/nginx/conf.d/myapp.local.conf 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. 3. Re-run the playbook to apply the changes and reload Nginx.
4. Remove the entry from your `/etc/hosts` file. 4. Remove the entry from your hosts file.