127 lines
4.0 KiB
Markdown
127 lines
4.0 KiB
Markdown
# Lenvi: Laravel & Legacy Environment Simplified
|
||
|
||
This playbook is built for Laravel development but can also run legacy PHP apps, offering a powerful, centralized environment with multi-php support on Ubuntu, or Ubuntu on WSL2; similar to Homestead but without the virtual machine overhead.
|
||
> WSL: Initial setup will stop for permission configuration reason, follow the instructions and run it properly again.
|
||
|
||
## Prerequisites
|
||
|
||
- **Ansible & Git:** Must be installed on the machine where you are running the playbook.
|
||
|
||
```bash
|
||
sudo apt update && sudo apt install ansible git -y
|
||
```
|
||
|
||
- **Sudo Access:** Your user must have `sudo` privileges to run the playbook.
|
||
|
||
## How to Run
|
||
|
||
### 1\. Setup: Get the Code
|
||
|
||
Clone the repository and go to the project 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.
|
||
**Example** `Lenvi.yaml`**:**
|
||
|
||
```yaml
|
||
db_engine: "mariadb" #mariadb, mysql or postgresql
|
||
db_credentials:
|
||
user: "Lenvi"
|
||
password: "secret"
|
||
|
||
sites:
|
||
- domain: local-api.laravel.com
|
||
project_root: /home/user/projects/my-laravel-app
|
||
document_root: /home/user/projects/my-laravel-app/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.
|
||
|
||
```bash
|
||
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`).
|
||
|
||
## 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:**
|
||
|
||
```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:**
|
||
|
||
```
|
||
127.0.0.1 local-api.laravel.com
|
||
127.0.0.1 local.phpmyadmin.com
|
||
```
|
||
|
||
### 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`**:**
|
||
|
||
```env
|
||
DB_CONNECTION=mysql
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=3306
|
||
DB_DATABASE=laravel_db
|
||
DB_USERNAME=lenvi
|
||
DB_PASSWORD=password
|
||
```
|
||
|
||
### 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.
|
||
|
||
```bash
|
||
cd /home/user/projects/my-laravel-app
|
||
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. |