add readme to env folder

env/README.md

@@ -0,0 +1,50 @@
+# 🔧 Environment Configuration Guide
+
+## 🌍 Overview
+This project uses **environment variables** to manage configuration across different environments (development, staging, production, etc.). These variables are loaded from `.env` files and can be overridden at multiple levels.
+
+---
+
+## 📌 **Environment Variable Priority (Lowest to Highest)**
+
+| 🔢 Priority | 📄 Source | 🔍 Description |
+|------------|-----------------------------|------------------------------------------------|
+| 1️⃣ **Fallback Values** | hardcoded defaults | Used only if no other configuration is provided |
+| 2️⃣ **Global Defaults** | `.env.all` | Shared settings for all services |
+| 3️⃣ **Service-Specific Overrides** | `.env.backend`, `.env.proxy`, etc. | Overrides `.env.all` with service-specific values |
+| 4️⃣ **Shell Environment Variables** | `export VAR=value` before running | Takes precedence over `.env` files |
+| 5️⃣ **CLI Overrides** | `docker compose --env-file` or `-e VAR=value` | **Highest priority** (for temporary overrides) |
+
+---
+
+## 🔄 **Overwriting Behavior**
+- 🏗 **Variables defined in `.env.all`** override fallback values.
+- 🏗 **Variables defined in `.env.<service>`** (e.g., `.env.backend`) override `.env.all`.
+- 🔧 **Manually exported environment variables** in the shell take priority over `.env` files.
+- 🚀 **Variables passed via CLI (`--env-file` or `-e VAR=value`)** override everything.
+
+---
+
+## 🚀 **Best Practices**
+✔️ **Use `.env.all` for global configurations** (e.g., `ENVIRONMENT=development`, `INFRASTRUCTURE_LABEL=myinfra`).  
+✔️ **Use `.env.<service>` for service-specific configurations** (e.g., `.env.backend` for Laravel, `.env.database` for MariaDB).  
+✔️ **If needed, manually override variables in the shell** using `export VAR=value`.  
+✔️ **Use CLI `--env-file` for temporary overrides** in testing/debugging scenarios.  
+
+---
+
+## 🏗 **Example File Structure**
+```sh
+/env/
+  ├── .env.all                  # Global default variables
+  ├── development/
+  │   ├── .env.backend          # Backend service config for development
+  │   ├── .env.database         # Database config for development
+  │   ├── .env.proxy            # Proxy config for development
+  ├── staging/
+  │   ├── .env.backend          # Backend service config for staging
+  │   ├── .env.database         # Database config for staging
+  ├── production/
+  │   ├── .env.backend          # Backend service config for production
+  │   ├── .env.database         # Database config for production
+