installer
This commit is contained in:
parent
cd3aafe684
commit
a1c287fbfb
183
README.md
183
README.md
@ -1,129 +1,116 @@
|
||||
# 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.
|
||||
|
||||
# Lenvi
|
||||
The name **Lenvi** stands for **L**aravel, **L**egacy, and **L**ightweight **Envi**ronment.
|
||||
It's a fast, simple alternative to tools like Homestead or Laragon that uses Ansible to provision your local Ubuntu machine (or WSL2) directly, without the overhead of a virtual machine. True to its name, Lenvi is tailored to handle modern **L**aravel applications and complex **L**egacy PHP sites with ease, all while remaining incredibly **L**ightweight.
|
||||
### Core Features
|
||||
* **No Virtual Machine:** Runs directly on Ubuntu 22.04+ (or WSL2 Ubuntu).
|
||||
* **Centralized Configuration:** Define your entire stack in one simple `Lenvi.yaml` file.
|
||||
* **Multi-PHP Ready:** Run different sites on different PHP versions simultaneously.
|
||||
* **Smart CLI Wrappers:** Automatically uses the correct PHP version for `php`, `composer`, and `artisan` commands based on your current project directory.
|
||||
* **Developer Utilities:** Easily enable tools like phpMyAdmin and Redis.
|
||||
* **WSL-Optimized:** Automatically configures WSL for optimal performance and file permissions.
|
||||
## Prerequisites
|
||||
|
||||
- **Ansible & Git:** Must be installed on the machine where you are running the playbook.
|
||||
|
||||
* **Ubuntu 22.04 or higher** (or WSL2 with Ubuntu).
|
||||
* **Ansible & Git:** Must be installed on the machine.
|
||||
```bash
|
||||
sudo apt update && sudo apt install ansible git -y
|
||||
```
|
||||
|
||||
- **Sudo Access:** Your user must have `sudo` privileges to run the playbook.
|
||||
|
||||
* **Sudo Access:** Your user must have `sudo` privileges.
|
||||
## How to Run
|
||||
|
||||
### 1\. Setup: Get the Code
|
||||
|
||||
Clone the repository and go to the project directory.
|
||||
|
||||
### 1. Get the Code
|
||||
Clone the repository to a convenient location, like your home directory.
|
||||
```bash
|
||||
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 wsl 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. /home/user/projects/laravel-app -> Very Fast!
|
||||
|
||||
**Example** `Lenvi.yaml`**:**
|
||||
|
||||
### 2. Configure Your Environment (`Lenvi.yaml`)
|
||||
This is the most important step. Open `Lenvi.yaml` and define your entire environment.
|
||||
```yaml
|
||||
db_engine: "mariadb" #mariadb, mysql or postgresql
|
||||
# ------------------------------------------------------------------
|
||||
# Lenvi: Central Configuration for Your Development Environment
|
||||
# ------------------------------------------------------------------
|
||||
# Optional developer utilities
|
||||
utilities:
|
||||
phpmyadmin:
|
||||
enabled: false
|
||||
domain: "pma.lenvi.local"
|
||||
php_version: "8.2"
|
||||
redis:
|
||||
enabled: false
|
||||
# 1. Database Engine: mariadb, mysql, or postgresql
|
||||
db_engine: "mariadb"
|
||||
# 2. Global Database Credentials
|
||||
db_credentials:
|
||||
user: "Lenvi"
|
||||
user: "Lenvi"
|
||||
password: "secret"
|
||||
|
||||
# 3. Your Web Projects
|
||||
sites:
|
||||
- domain: local-api.laravel.com
|
||||
project_root: /home/user/projects/my-laravel-app
|
||||
document_root: /home/user/projects/my-laravel-app/public
|
||||
- domain: mylaravelapp.local
|
||||
project_root: /home/lenvi/projects/laravel
|
||||
document_root: /home/lenvi/projects/laravel/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.
|
||||
|
||||
**Key Configuration Options:**
|
||||
* **`utilities`**: Set `enabled: true` to install optional tools like `phpmyadmin` and `redis`.
|
||||
* **`db_engine`**: Choose between `mariadb`, `mysql`, or `postgresql`. Lenvi will install and manage the correct service.
|
||||
* **`sites`**: A list of all your projects.
|
||||
* `domain`: The local domain name you'll use in the browser.
|
||||
* `project_root`: The base directory of your project (where `.git` or `composer.json` lives).
|
||||
* `document_root`: The public-facing directory Nginx serves (e.g., `/public` for Laravel).
|
||||
* `php_version`: The PHP version for this specific site.
|
||||
* `database`: (Optional) The name of the database to create for this site.
|
||||
> **WSL Performance Tip:** For the best performance, keep your project files inside the WSL filesystem (e.g., `/home/user/projects`) rather than on the mounted Windows filesystem (e.g., `/mnt/c/Users/...`).
|
||||
### 3. Run the Provisioning Script
|
||||
To set up or update your environment, use the simple `lenvi.sh` script.
|
||||
First, make the script executable (you only need to do this once):
|
||||
```bash
|
||||
ansible-playbook playbook.yml -i inventory --ask-become-pass
|
||||
chmod +x lenvi.sh
|
||||
```
|
||||
|
||||
> **\--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:**
|
||||
|
||||
Now, run the script. It will handle everything for you and will prompt for your `sudo` password to perform the necessary system changes.
|
||||
```bash
|
||||
./lenvi.sh
|
||||
```
|
||||
> **WSL Users:** The very first time you run this, the script may stop and ask you to restart WSL. This is a one-time setup step to fix file permissions. Follow the on-screen instructions, and then re-run `./lenvi.sh`.
|
||||
## Post-Installation
|
||||
### 1. Update Your `hosts` File
|
||||
For your browser to access local domains, you must map them to your local machine.
|
||||
* **On Linux:** Edit `/etc/hosts`.
|
||||
```bash
|
||||
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:**
|
||||
|
||||
* **On Windows (for WSL):** Open **Notepad as an Administrator** and edit `C:\Windows\System32\drivers\etc\hosts`.
|
||||
Add an entry for each domain defined in `Lenvi.yaml`:
|
||||
```
|
||||
127.0.0.1 local-api.laravel.com
|
||||
127.0.0.1 local.phpmyadmin.com
|
||||
127.0.0.1 mylaravelapp.local
|
||||
# Add other project domains here
|
||||
# Add utility domains if enabled, e.g.:
|
||||
# 127.0.0.1 pma.lenvi.local
|
||||
```
|
||||
|
||||
### 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`**:**
|
||||
|
||||
### 2. Configure Your Application (`.env`)
|
||||
Update your application's `.env` file to use the database credentials from `Lenvi.yaml`.
|
||||
**Example `.env` for `mylaravelapp.local`:**
|
||||
```env
|
||||
DB_CONNECTION=mysql
|
||||
DB_CONNECTION=mysql # Works for both mysql and mariadb
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=laravel_db
|
||||
DB_USERNAME=lenvi
|
||||
DB_PASSWORD=password
|
||||
DB_USERNAME=Lenvi
|
||||
DB_PASSWORD=secret
|
||||
# If you enabled Redis in Lenvi.yaml
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PASSWORD=null
|
||||
REDIS_PORT=6379
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
### 3. Verify Your Setup
|
||||
* **Web Access:** Open your browser and navigate to `http://mylaravelapp.local`.
|
||||
* **Smart PHP Version:** The `php`, `composer`, and `artisan` commands are context-aware.
|
||||
```bash
|
||||
cd /home/user/projects/my-laravel-app
|
||||
cd /home/lenvi/projects/laravel
|
||||
php --version # Will show the PHP version defined for this site
|
||||
composer install
|
||||
```
|
||||
|
||||
## Daily Workflow
|
||||
|
||||
### Adding a New Site
|
||||
|
||||
1. Add a new project block to the `sites` list in `Lenvi.yaml`.
|
||||
2. Add the new domain to your hosts file.
|
||||
3. Re-run the playbook.
|
||||
|
||||
### Changing a Site's PHP Version
|
||||
|
||||
1. In `Lenvi.yaml`, change the `php_version` for the desired site.
|
||||
2. Re-run the playbook.
|
||||
|
||||
### Removing a Site
|
||||
|
||||
1. Delete the project's block from `Lenvi.yaml`.
|
||||
2. Manually delete the site's Nginx configuration file (e.g., `sudo rm /etc/nginx/conf.d/local-api.laravel.com.conf`).
|
||||
3. Re-run the playbook and remove the entry from your hosts file.
|
||||
Lenvi is designed to be declarative. To make any changes, simply edit `Lenvi.yaml` and re-run the provisioning script with `./lenvi.sh`.
|
||||
* **To Add a New Site:** Add a new entry to the `sites` list, update your `hosts` file, and run `./lenvi.sh`.
|
||||
* **To Remove a Site:** Delete the site's block from `Lenvi.yaml`. When you re-run `./lenvi.sh`, Lenvi will automatically remove its Nginx configuration.
|
||||
* **To Change a PHP Version:** Update the `php_version` for a site and run `./lenvi.sh`.
|
||||
* **To Enable a Utility:** Set `enabled: true` for `phpmyadmin` or `redis`, update your `hosts` file if needed, and run `./lenvi.sh`.
|
||||
29
lenvi.sh
Normal file
29
lenvi.sh
Normal file
@ -0,0 +1,29 @@
|
||||
#!/bin/bash
|
||||
|
||||
# --- Lenvi Provisioning Script ---
|
||||
# This script simplifies running the Ansible playbook, making it accessible
|
||||
# for users who are not familiar with Ansible.
|
||||
|
||||
# Find the script's own directory to run from the correct location,
|
||||
# ensuring that playbook.yml and other files are found.
|
||||
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
|
||||
cd "$SCRIPT_DIR"
|
||||
|
||||
echo "▶️ Starting Lenvi Provisioning..."
|
||||
echo " This will install/update services based on your Lenvi.yaml configuration."
|
||||
echo " You will be prompted for your sudo password to make system changes."
|
||||
echo ""
|
||||
|
||||
# Execute the Ansible playbook.
|
||||
# The `if` statement checks the command's exit code to provide a clear success/failure message.
|
||||
if ansible-playbook playbook.yml -i inventory --ask-become-pass; then
|
||||
echo ""
|
||||
echo "✅ Success! Your Lenvi environment has been provisioned."
|
||||
echo " Don't forget to update your hosts file if you added or changed site domains."
|
||||
echo ""
|
||||
else
|
||||
echo ""
|
||||
echo "❌ Error: Lenvi provisioning failed." >&2
|
||||
echo " Please review the Ansible output above to diagnose the issue." >&2
|
||||
exit 1
|
||||
fi
|
||||
@ -44,9 +44,14 @@
|
||||
register: wsl_conf_result
|
||||
when: is_wsl | default(false)
|
||||
|
||||
- name: "STOP PLAYBOOK: Force user to restart WSL if wsl.conf was changed"
|
||||
- name: Ensure /home/{{ ansible_user_id }} is executable by all (chmod +x)
|
||||
ansible.builtin.file:
|
||||
path: "/home/{{ ansible_user_id }}"
|
||||
mode: '0711'
|
||||
|
||||
- name: "FOR WSL USER: This error is safe and intentional. Follow instructions below."
|
||||
ansible.builtin.fail:
|
||||
msg: |
|
||||
🛑 ACTION REQUIRED: WSL Configuration Was Updated! The playbook has configured /etc/wsl.conf to fix file permissions. You MUST restart WSL for this change to take effect. The playbook has been stopped. Please perform the following steps: 1. Close this terminal. 2. Open Windows PowerShell or CMD (not as admin). 3. Run the command: wsl --shutdown 4. Wait a few seconds, then re-open your WSL terminal and cd ~/Lenvi. 5. Re-run the Lenvi playbook: ansible-playbook playbook.yml -i inventory --ask-become-pass After restarting, your file permission issues will be permanently solved.
|
||||
✅ ACTION REQUIRED: WSL Configuration was Updated! Lenvi has configured /etc/wsl.conf to fix file permissions. You MUST restart WSL for this change to take effect. Please perform the following steps: 1. Close this terminal. 2. Open Windows PowerShell or CMD (not as admin). 3. Run the command: wsl --shutdown 4. Wait a few seconds, then re-open your WSL terminal and cd ~/Lenvi. 5. Re-run ./lenvi.sh
|
||||
|
||||
when: wsl_conf_result.changed
|
||||
Loading…
x
Reference in New Issue
Block a user