152 lines
4.0 KiB
Markdown
152 lines
4.0 KiB
Markdown
# 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
|