72d0b66be7
- Added a new section for operational runbooks in README.md, detailing procedures for incident response, database operations, and queue management. - Updated the documentation structure in STRUCTURE.md to reflect the new organization of guides and resources. - Removed the deprecated disabled-modules.md file to streamline documentation. - Enhanced the _archive/README.md with historical notes on documentation alignment and corrections made in December 2025. - Updated various references in the documentation to reflect the new paths and services in the integrations directory.
203 lines
4.7 KiB
Markdown
203 lines
4.7 KiB
Markdown
# 🚀 Getting Started
|
|
|
|
## ✅ **Environment File Options**
|
|
|
|
We provide **environment-specific templates** for easy setup:
|
|
|
|
### 📁 **Available Templates:**
|
|
|
|
Located in the `env/` folder:
|
|
|
|
- 🔸 **`env/dev.env.sample`** - Development environment template
|
|
- 🔸 **`env/portal-backend.env.sample`** - Backend-specific variables reference
|
|
- 🔸 **`env/portal-frontend.env.sample`** - Frontend-specific variables reference
|
|
|
|
### 🎯 **Benefits:**
|
|
|
|
- ✅ **Environment-specific**: Clear separation of dev vs prod
|
|
- ✅ **Secure defaults**: Production uses strong security settings
|
|
- ✅ **Easy setup**: Copy the template for your needs
|
|
- ✅ **No confusion**: Clear instructions for each environment
|
|
|
|
## 🔧 **Environment File Structure**
|
|
|
|
```
|
|
📦 Customer Portal
|
|
├── env/
|
|
│ ├── dev.env.sample # 🔸 Development template
|
|
│ ├── portal-backend.env.sample # Backend variables
|
|
│ └── portal-frontend.env.sample # Frontend variables
|
|
├── .env # ✅ Your actual config (gitignored)
|
|
├── apps/
|
|
│ ├── bff/ # 🚀 Backend reads from root .env
|
|
│ └── portal/ # 🚀 Frontend reads from root .env
|
|
└── ...
|
|
```
|
|
|
|
**How it works:**
|
|
|
|
- **Frontend (Next.js)**: Automatically reads `.env` from project root
|
|
- **Backend (NestJS)**: Automatically reads `.env` from project root
|
|
- **Docker**: We pass env vars from root `.env` to containers
|
|
|
|
## 🚀 **Quick Start (2 minutes)**
|
|
|
|
### 1. Setup Environment
|
|
|
|
**🔸 For Development:**
|
|
|
|
```bash
|
|
# Copy development environment template
|
|
cp env/dev.env.sample .env
|
|
|
|
# Edit with your dev values (most defaults work!)
|
|
nano .env # Configure for local development
|
|
```
|
|
|
|
**🔸 For Production:**
|
|
|
|
```bash
|
|
# Start from the development template and adjust for production
|
|
cp env/dev.env.sample .env
|
|
|
|
# Edit with your production values (REQUIRED!)
|
|
nano .env # Replace with secure production values
|
|
```
|
|
|
|
### 2. Start Development
|
|
|
|
```bash
|
|
# Start database and Redis services
|
|
pnpm dev:start
|
|
|
|
# In another terminal, start the applications
|
|
pnpm dev
|
|
```
|
|
|
|
**That's it!** Both frontend and backend will use the same `.env` file.
|
|
|
|
## 📋 **What Each App Reads**
|
|
|
|
### **Backend (apps/bff/)**
|
|
|
|
Reads these variables from root `.env`:
|
|
|
|
```bash
|
|
DATABASE_URL # Database connection
|
|
REDIS_URL # Cache connection
|
|
JWT_SECRET # Authentication
|
|
WHMCS_BASE_URL # External API
|
|
SF_LOGIN_URL # Salesforce API
|
|
PORTAL_PRICEBOOK_ID # Salesforce pricing pricebook
|
|
LOG_LEVEL # Logging level
|
|
# ... and all backend variables
|
|
```
|
|
|
|
### **Frontend (apps/portal/)**
|
|
|
|
Reads these variables from root `.env`:
|
|
|
|
```bash
|
|
NEXT_PUBLIC_API_BASE # Backend API URL
|
|
NEXT_PUBLIC_APP_NAME # App branding
|
|
NEXT_PUBLIC_APP_VERSION # Version display
|
|
NEXT_PUBLIC_ENABLE_DEVTOOLS # Development tools
|
|
# ... only NEXT_PUBLIC_ variables are exposed to browser
|
|
```
|
|
|
|
## 🛠️ **Development Workflow**
|
|
|
|
### Daily Development
|
|
|
|
```bash
|
|
# 1. Start services (run once)
|
|
pnpm dev:start
|
|
|
|
# 2. Start apps (with hot reload)
|
|
pnpm dev
|
|
```
|
|
|
|
### Environment Changes
|
|
|
|
```bash
|
|
# Edit the single .env file
|
|
nano .env
|
|
|
|
# Restart apps to pick up changes
|
|
# (Services like database don't need restart)
|
|
pnpm dev
|
|
```
|
|
|
|
### Database Management
|
|
|
|
```bash
|
|
# Run migrations
|
|
pnpm dev:migrate
|
|
|
|
# Open database admin tool
|
|
pnpm dev:tools
|
|
# Visit http://localhost:8080 for Adminer
|
|
```
|
|
|
|
## 🚀 **Production Deployment**
|
|
|
|
### For Production
|
|
|
|
```bash
|
|
# 1. Copy template
|
|
cp .env.example .env
|
|
|
|
# 2. Edit for production values
|
|
nano .env
|
|
# Set strong passwords, production URLs, etc.
|
|
|
|
# 3. Deploy
|
|
pnpm prod:deploy
|
|
```
|
|
|
|
## 🔍 **Key Benefits**
|
|
|
|
### **Single Source of Truth**
|
|
|
|
- ✅ One file to rule them all
|
|
- ✅ No confusion about which file to edit
|
|
- ✅ No duplicate values to maintain
|
|
- ✅ Consistent configuration across apps
|
|
|
|
### **Standard Approach**
|
|
|
|
- ✅ Follows Next.js conventions
|
|
- ✅ Follows NestJS conventions
|
|
- ✅ Follows Docker conventions
|
|
- ✅ Industry best practice
|
|
|
|
### **Developer Friendly**
|
|
|
|
- ✅ Simple setup: copy one file
|
|
- ✅ Easy to understand structure
|
|
- ✅ No app-specific configuration needed
|
|
- ✅ Works with all tools (VS Code, Docker, etc.)
|
|
|
|
## 🚨 **Important Notes**
|
|
|
|
### **Security**
|
|
|
|
- ✅ `.env.example` is committed (safe template)
|
|
- ✅ `.env` is gitignored (contains secrets)
|
|
- ✅ Never commit actual `.env` file to git
|
|
- ✅ Use strong values for production
|
|
|
|
### **Variable Naming**
|
|
|
|
- ✅ `NEXT_PUBLIC_*` = Exposed to browser (frontend)
|
|
- ✅ Everything else = Server-side only (backend)
|
|
- ✅ Clear naming convention
|
|
|
|
### **Environment Separation**
|
|
|
|
- ✅ Development: Use local services (localhost)
|
|
- ✅ Production: Use container services (service names)
|
|
- ✅ Same file structure, different values
|
|
|
|
This approach is **simple, standard, and scalable**! 🎉
|