barsa 72d0b66be7 Enhance Documentation Structure and Update Operational Runbooks

- 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.

2025-12-23 15:55:58 +09:00

4.7 KiB

Raw Blame History

🚀 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:

# 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:

# 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

# 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:

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:

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

# 1. Start services (run once)
pnpm dev:start

# 2. Start apps (with hot reload)
pnpm dev

Environment Changes

# Edit the single .env file
nano .env

# Restart apps to pick up changes
# (Services like database don't need restart)
pnpm dev

Database Management

# Run migrations
pnpm dev:migrate

# Open database admin tool
pnpm dev:tools
# Visit http://localhost:8080 for Adminer

🚀 Production Deployment

For Production

# 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! 🎉

4.7 KiB Raw Blame History