Assist_Design/docs/GETTING_STARTED.md

🚀 Getting Started with Customer Portal

✅ Environment File Options

We provide environment-specific templates for easy setup:

📁 Available Templates:

• 🔸 .env.example - Standard environment template for all environments
• 🔸 Environment-specific values - Adjust settings based on development vs production needs

🎯 Benefits:

• ✅ Environment-specific: Clear separation of dev vs prod
• ✅ Secure defaults: Production uses strong security settings
• ✅ Easy setup: Copy the right template for your needs
• ✅ No confusion: Clear instructions for each environment

🔧 Environment File Structure

📦 Customer Portal
├── .env.example          # 🔸 Environment template
├── .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 environment template
cp .env.example .env

# Edit with your dev values (most defaults work!)
nano .env  # Configure for local development

🔸 For Production:

# Copy environment template  
cp .env.example .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! 🎉