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)
```bash
# Set this to your actual API URL
NEXT_PUBLIC_API_BASE="https://api.yourdomain.com"
```

### Common Examples:
```bash
# 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
```bash
# Frontend: https://yourdomain.com
# Backend: https://yourdomain.com/api
NEXT_PUBLIC_API_BASE="/api"
```

### Scenario 2: Separate API Server
```bash
# Frontend: https://portal.yourdomain.com
# Backend: https://api.yourdomain.com
NEXT_PUBLIC_API_BASE="https://api.yourdomain.com"
```

### Scenario 3: Docker/Kubernetes Deployment
```bash
# Using service discovery
NEXT_PUBLIC_API_BASE="https://backend-service/api"
```

## 🛠️ Setup Instructions

### Development Setup
1. Copy the example file:
   ```bash
   cp apps/portal/.env.example apps/portal/.env.local
   ```

2. Update values as needed:
   ```bash
   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:
```typescript
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

```dockerfile
# 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