Assist_Design/docs/ENVIRONMENT_CONFIGURATION.md

Environment Configuration Guide

🌍 Overview

This guide explains how to configure the Customer Portal for different environments (development, staging, production).

📁 Environment Files

File Structure

apps/portal/
├── .env.local          # Local development (ignored by git)
├── .env.example        # Template for local setup
└── .env.production     # Production environment template

Priority Order

1. .env.local (highest priority, for local overrides)
2. .env.production (when NODE_ENV=production)
3. Fallback to http://localhost:4000 (development default)

🔧 API Base Configuration

Simple Configuration (Recommended)

# Set this to your actual API URL
NEXT_PUBLIC_API_BASE="https://api.yourdomain.com"

Common Examples:

# Same domain with /api path
NEXT_PUBLIC_API_BASE="https://yourdomain.com/api"

# Separate API subdomain  
NEXT_PUBLIC_API_BASE="https://api.yourdomain.com"

# Different port
NEXT_PUBLIC_API_BASE="https://yourdomain.com:4000"

# Development (default fallback)
NEXT_PUBLIC_API_BASE="http://localhost:4000"

🚀 Deployment Scenarios

Scenario 1: Frontend + Backend on Same Server

# Frontend: https://yourdomain.com
# Backend: https://yourdomain.com/api
NEXT_PUBLIC_API_BASE="/api"

Scenario 2: Separate API Server

# Frontend: https://portal.yourdomain.com
# Backend: https://api.yourdomain.com
NEXT_PUBLIC_API_BASE="https://api.yourdomain.com"

Scenario 3: Docker/Kubernetes Deployment

# Using service discovery
NEXT_PUBLIC_API_BASE="https://backend-service/api"

🛠️ Setup Instructions

Development Setup

1. Copy the example file:

   cp apps/portal/.env.example apps/portal/.env.local
   

2. Update values as needed:

   NEXT_PUBLIC_API_BASE="http://localhost:4000"
   

Production Setup

1. Set environment variables in your deployment platform:

   • Vercel: Add to project settings
   • Docker: Use environment files or compose
   • Kubernetes: Use ConfigMaps/Secrets

2. Choose appropriate API base configuration

Environment Variables Reference

Variable	Description	Example
NEXT_PUBLIC_API_BASE	Backend API base URL	https://api.example.com
NEXT_PUBLIC_APP_NAME	Application display name	Customer Portal
NEXT_PUBLIC_APP_VERSION	Version displayed in UI	1.0.0
NODE_ENV	Environment mode	production
HOSTNAME	Server bind address	0.0.0.0
PORT	Server port	3000

🔍 Troubleshooting

Common Issues

1. CORS Errors in Production

   • Ensure backend allows frontend domain
   • Check API base URL is correct

2. 404 Errors for API Calls

   • Verify NEXT_PUBLIC_API_BASE is set correctly
   • Check network tab in browser dev tools

3. Auto-detection Not Working

   • Set explicit NEXT_PUBLIC_API_BASE
   • Check console for API base URL being used

Debug API Configuration

Add this to any component to see current API base:

console.log('API Base:', process.env.NEXT_PUBLIC_API_BASE || 'auto-detected');

🔒 Security Considerations

1. HTTPS in Production: Always use HTTPS for production APIs
2. Environment Secrets: Use proper secret management for sensitive data
3. CORS Configuration: Restrict backend CORS to known frontend domains
4. API Keys: Use environment variables, never hardcode

📦 Docker Deployment Example

# Production build with environment
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN pnpm build

# Set production environment
ENV NODE_ENV=production
ENV NEXT_PUBLIC_API_BASE="https://api.example.com"

EXPOSE 3000
CMD ["pnpm", "start"]

🎯 Best Practices

1. Use auto-detection for simple same-domain deployments
2. Set explicit URLs for complex multi-service architectures
3. Test environment configurations before deployment
4. Document your specific deployment setup
5. Use staging environments to verify configuration