readme updated
This commit is contained in:
parent
23b08fb56b
commit
a97c8e77eb
134
README.md
134
README.md
@ -1,54 +1,100 @@
|
||||
# Lenvi Ansible Provisioner
|
||||
|
||||
Lenvi is a lightweight, Ansible-powered tool for managing local Laravel development environments. It provides a Homestead-like experience without the overhead of a virtual machine, running natively on Linux or on Windows via WSL2.
|
||||
|
||||
# 🧰 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 `lenvi.yaml` file.
|
||||
- **Multi-PHP:** Assign a specific PHP version (e.g., 8.0, 8.2, 8.3) to each site.
|
||||
- **Database Support:** Automatically creates databases using a shared MariaDB, MySQL, or PostgreSQL server.
|
||||
- **Idempotent:** Safely run the provisioner at any time to update your environment.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Ansible:** You must have Ansible installed.
|
||||
- **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`:
|
||||
```bash
|
||||
# On Debian/Ubuntu
|
||||
sudo apt update
|
||||
sudo apt install python3-pip -y
|
||||
pip3 install ansible
|
||||
sudo apt install software-properties-common
|
||||
sudo add-apt-repository --yes --update ppa:ansible/ansible
|
||||
sudo apt install ansible
|
||||
```
|
||||
2. **WSL2 (for Windows users):** Install WSL2 and a Linux distribution like **Ubuntu 22.04** from the Microsoft Store. All subsequent commands must be run from the WSL2 terminal.
|
||||
|
||||
## How to Use
|
||||
|
||||
1. **Clone this repository:**
|
||||
### 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`:**
|
||||
```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.
|
||||
```bash
|
||||
git clone <your-repo-url> ~/tools/lenvi_ansible
|
||||
cd /path/to/lenvi-ansible
|
||||
ansible-playbook playbook.yml
|
||||
```
|
||||
|
||||
2. **Configure `lenvi.yaml`:**
|
||||
Open `~/tools/lenvi_ansible/lenvi.yaml` and configure it for your projects. Set your `db_engine` and list all your sites under the `sites` key.
|
||||
|
||||
3. **Run the Playbook:**
|
||||
Navigate to the `lenvi_ansible` directory and run the main playbook.
|
||||
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:
|
||||
```bash
|
||||
cd ~/tools/lenvi_ansible
|
||||
ansible-playbook playbook.yml --ask-become-pass
|
||||
sudo nano /etc/hosts
|
||||
```
|
||||
Ansible will ask for your `sudo` password to install software and configure services.
|
||||
|
||||
### Important Note for Windows (WSL2) Users
|
||||
|
||||
For your Windows browser (Chrome, Firefox, etc.) to access a site like `myapp.test`, you must manually edit the **Windows hosts file**.
|
||||
|
||||
1. Open **Notepad** as an **Administrator**.
|
||||
2. Open the file: `C:\Windows\System32\drivers\etc\hosts`
|
||||
3. For each site in your `lenvi.yaml`, add a new line:
|
||||
Add an entry for each site you defined in `Lenvi.yaml`, pointing to your local IP address.
|
||||
```
|
||||
127.0.0.1 myapp.test
|
||||
127.0.0.1 another-app.test
|
||||
127.0.0.1 myapp.local
|
||||
127.0.0.1 legacy-app.local
|
||||
```
|
||||
4. Save the file. You only need to do this once per new domain.
|
||||
|
||||
You can now access your sites in your browser!
|
||||
**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:
|
||||
```bash
|
||||
# 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.
|
||||
Loading…
x
Reference in New Issue
Block a user