78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# 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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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`:**
|
|
```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.
|
|
```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`).
|
|
## 🚀 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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. |