Assist_Design/docs/DEVELOPMENT_SETUP.md

🛠️ Development Setup Guide

🔒 Environment Files Security

✅ Safe for Development

Your .env files are automatically excluded from git commits via .gitignore. This means you can:

• ✅ Keep real credentials in .env files locally
• ✅ Develop with actual API connections
• ✅ Test with real data safely
• ✅ Never worry about committing secrets

📁 Environment File Structure

apps/bff/
├── .env                 # Your actual credentials (git ignored)
├── .env.example         # Template with placeholder values (committed)
├── .env.production      # Production template (committed)
└── .env.production.example # Production example (committed)

apps/portal/
├── .env.local           # Your local overrides (git ignored)
├── .env.example         # Template (committed)
└── .env.production      # Production template (committed)

🚀 Quick Setup

1. Backend Environment Setup

cd apps/bff
cp .env.example .env
nano .env  # Update with your actual values

2. Frontend Environment Setup

cd apps/portal
cp .env.example .env.local
nano .env.local  # Update if needed (usually defaults are fine)

3. Salesforce Private Key

# Create secrets directory if not exists
mkdir -p secrets

# Add your Salesforce private key
nano secrets/sf-private.key
chmod 600 secrets/sf-private.key

🔧 Configuration Checklist

Backend (.env)

• DATABASE_URL - Your PostgreSQL connection
• REDIS_URL - Your Redis connection
• WHMCS_BASE_URL - Your WHMCS installation URL
• WHMCS_API_IDENTIFIER - Your WHMCS API identifier
• WHMCS_API_SECRET - Your WHMCS API secret
• SF_LOGIN_URL - Salesforce login URL
• SF_CLIENT_ID - Salesforce Connected App consumer key
• SF_USERNAME - Salesforce integration user email
• JWT_SECRET - Generate with: openssl rand -hex 64

Frontend (.env.local)

• NEXT_PUBLIC_API_BASE - Usually http://localhost:4000 for development

🎯 Development Commands

# Install dependencies
pnpm install

# Start development servers
pnpm dev

# Type checking
pnpm type-check

# Build for production test
pnpm build

🔒 Security Best Practices

✅ DO:

• Keep .env files for local development
• Use strong, unique passwords
• Generate secure JWT secrets
• Set proper file permissions (chmod 600) for private keys
• Test with real but non-production data when possible

❌ DON'T:

• Ever commit .env files to git
• Share credentials in chat/email
• Use production secrets in development
• Hardcode secrets in source code
• Use weak or default passwords

🚨 If You Accidentally Commit Secrets

1. Immediately rotate all exposed credentials
2. Remove from git history:

   git filter-branch --force --index-filter \
     "git rm --cached --ignore-unmatch path/to/secret/file" \
     --prune-empty --tag-name-filter cat -- --all
   

3. Force push to overwrite history: git push --force
4. Update all team members

🌍 Environment-Specific Configuration

Development

• Uses .env files
• Connects to local/development services
• Verbose logging enabled
• CORS permissive for localhost

Production

• Uses environment variables from deployment platform
• Connects to production services
• Structured logging
• Strict CORS and security headers

🛠️ Troubleshooting

"Environment variable not found"

1. Check .env file exists and has the variable
2. Restart development server
3. Check variable name spelling

"Database connection failed"

1. Verify PostgreSQL is running
2. Check DATABASE_URL format
3. Test connection manually

"Salesforce authentication failed"

1. Verify private key file exists and permissions
2. Check Connected App configuration
3. Verify user permissions in Salesforce

"WHMCS API errors"

1. Verify API credentials are correct
2. Check IP whitelist in WHMCS
3. Test API endpoints manually with curl

📖 Additional Resources

• Environment Configuration Guide
• Quick Start Deployment Guide
• Plesk Deployment Guide
• Salesforce Setup Guide
• WHMCS Integration Guide