docs: add comprehensive unified configuration documentation
- Create detailed README for unified configuration system - Document configuration structure and environment overrides - Provide environment variables reference and best practices - Include migration guide from legacy configuration system - Add troubleshooting section and security considerations - Document all available scripts and generation commands
This commit is contained in:
William Valentin
411
config/README.md
Normal file
411
config/README.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# Unified Configuration System
|
||||
|
||||
This directory contains the unified configuration system for the RxMinder application. The unified config provides a single source of truth for all application settings across different environments and deployment targets.
|
||||
|
||||
## Overview
|
||||
|
||||
The unified configuration system replaces the previous scattered approach of multiple `.env` files and environment-specific configurations with a centralized, type-safe, and environment-aware system.
|
||||
|
||||
### Key Benefits
|
||||
|
||||
- 🎯 **Single Source of Truth**: All configuration in one place
|
||||
- 🔒 **Type Safety**: Full TypeScript support with interfaces
|
||||
- 🌍 **Environment Aware**: Automatic environment-specific overrides
|
||||
- 🚀 **Auto-Generation**: Generates all necessary config files automatically
|
||||
- 🔄 **Easy Migration**: Smooth transition from old config system
|
||||
- 📝 **Self-Documenting**: Clear structure with validation
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
config/
|
||||
├── README.md # This documentation
|
||||
├── unified.config.ts # Main unified configuration
|
||||
├── app.config.ts # Legacy config (deprecated)
|
||||
└── generated/ # Auto-generated configs
|
||||
├── development.config.ts
|
||||
├── staging.config.ts
|
||||
└── production.config.ts
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Using the Unified Config
|
||||
|
||||
```typescript
|
||||
import { unifiedConfig, isProduction, featureFlags } from './config/unified.config';
|
||||
|
||||
// Access configuration
|
||||
const dbUrl = unifiedConfig.database.url;
|
||||
const appName = unifiedConfig.app.name;
|
||||
|
||||
// Use convenience exports
|
||||
if (isProduction()) {
|
||||
// Production-specific logic
|
||||
}
|
||||
|
||||
if (featureFlags.enableOAuth) {
|
||||
// OAuth-enabled logic
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Environment Variables
|
||||
|
||||
The system reads from environment variables with fallbacks to sensible defaults:
|
||||
|
||||
```bash
|
||||
# Required variables
|
||||
APP_NAME=RxMinder
|
||||
NODE_ENV=production
|
||||
VITE_COUCHDB_URL=http://couchdb:5984
|
||||
|
||||
# Optional variables with defaults
|
||||
APP_VERSION=1.0.0
|
||||
DEBUG_MODE=false
|
||||
ENABLE_OAUTH=true
|
||||
```
|
||||
|
||||
### 3. Generating Config Files
|
||||
|
||||
Generate configuration files for all environments:
|
||||
|
||||
```bash
|
||||
# Generate for all environments
|
||||
make generate-config
|
||||
|
||||
# Generate for specific environment
|
||||
make generate-config-prod
|
||||
|
||||
# Validate configuration
|
||||
make validate-config
|
||||
|
||||
# Debug current config
|
||||
make config-debug
|
||||
```
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
### Application Settings
|
||||
|
||||
```typescript
|
||||
app: {
|
||||
name: string; // Application name
|
||||
version: string; // Version number
|
||||
environment: Environment; // Current environment
|
||||
baseUrl: string; // Base application URL
|
||||
port: number; // Server port
|
||||
}
|
||||
```
|
||||
|
||||
### Database Configuration
|
||||
|
||||
```typescript
|
||||
database: {
|
||||
url: string; // Database connection URL
|
||||
username: string; // Database username
|
||||
password: string; // Database password
|
||||
name: string; // Database name
|
||||
useMock: boolean; // Use mock database for testing
|
||||
connectionTimeout: number;
|
||||
retryAttempts: number;
|
||||
}
|
||||
```
|
||||
|
||||
### Kubernetes Configuration
|
||||
|
||||
```typescript
|
||||
kubernetes: {
|
||||
namespace: string; // K8s namespace
|
||||
ingressHost: string; // Ingress hostname
|
||||
replicas: {
|
||||
frontend: number; // Frontend replica count
|
||||
database: number; // Database replica count
|
||||
}
|
||||
resources: {
|
||||
frontend: ResourceLimits;
|
||||
database: ResourceLimits;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
|
||||
```typescript
|
||||
features: {
|
||||
enableEmailVerification: boolean;
|
||||
enableOAuth: boolean;
|
||||
enableAdminInterface: boolean;
|
||||
enableMonitoring: boolean;
|
||||
debugMode: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Overrides
|
||||
|
||||
The system supports environment-specific overrides:
|
||||
|
||||
### Development
|
||||
|
||||
- Debug mode enabled
|
||||
- Lower resource limits
|
||||
- Console logging for emails
|
||||
- Hot reload enabled
|
||||
|
||||
### Staging
|
||||
|
||||
- Monitoring enabled
|
||||
- Production-like settings
|
||||
- Staging URLs
|
||||
- Moderate resource limits
|
||||
|
||||
### Production
|
||||
|
||||
- Security features enabled
|
||||
- Higher resource limits
|
||||
- Performance optimizations
|
||||
- Monitoring and metrics enabled
|
||||
|
||||
## Environment Variables Reference
|
||||
|
||||
### Core Application
|
||||
|
||||
- `APP_NAME` - Application name (default: RxMinder)
|
||||
- `APP_VERSION` - Version number (default: 1.0.0)
|
||||
- `APP_BASE_URL` - Base URL (default: http://localhost:5173)
|
||||
- `NODE_ENV` - Environment (development/staging/production/test)
|
||||
|
||||
### Database
|
||||
|
||||
- `VITE_COUCHDB_URL` - CouchDB URL
|
||||
- `VITE_COUCHDB_USER` - CouchDB username
|
||||
- `VITE_COUCHDB_PASSWORD` - CouchDB password
|
||||
- `USE_MOCK_DB` - Use mock database (default: false)
|
||||
|
||||
### Container & Deployment
|
||||
|
||||
- `CONTAINER_REGISTRY` - Container registry URL
|
||||
- `CONTAINER_REPOSITORY` - Repository name
|
||||
- `CONTAINER_TAG` - Container tag
|
||||
- `INGRESS_HOST` - Kubernetes ingress host
|
||||
- `STORAGE_CLASS` - Kubernetes storage class
|
||||
- `STORAGE_SIZE` - Storage size (default: 1Gi)
|
||||
|
||||
### Email Configuration
|
||||
|
||||
- `VITE_MAILGUN_API_KEY` - Mailgun API key
|
||||
- `VITE_MAILGUN_DOMAIN` - Mailgun domain
|
||||
- `VITE_MAILGUN_FROM_NAME` - From name (default: RxMinder)
|
||||
- `VITE_MAILGUN_FROM_EMAIL` - From email address
|
||||
|
||||
### OAuth Configuration
|
||||
|
||||
- `VITE_GOOGLE_CLIENT_ID` - Google OAuth client ID
|
||||
- `VITE_GITHUB_CLIENT_ID` - GitHub OAuth client ID
|
||||
|
||||
### Feature Flags
|
||||
|
||||
- `ENABLE_EMAIL_VERIFICATION` - Enable email verification (default: true)
|
||||
- `ENABLE_OAUTH` - Enable OAuth (default: true)
|
||||
- `ENABLE_ADMIN_INTERFACE` - Enable admin interface (default: true)
|
||||
- `ENABLE_MONITORING` - Enable monitoring (default: false)
|
||||
- `DEBUG_MODE` - Enable debug mode (default: false)
|
||||
|
||||
### Security & Performance
|
||||
|
||||
- `JWT_SECRET` - JWT signing secret
|
||||
- `LOG_LEVEL` - Logging level (debug/info/warn/error)
|
||||
- `CACHE_TTL` - Cache timeout in seconds
|
||||
- `REQUEST_TIMEOUT` - Request timeout in milliseconds
|
||||
|
||||
## Generated Files
|
||||
|
||||
The unified config system generates several files:
|
||||
|
||||
### 1. Environment Files
|
||||
|
||||
- `.env.development` - Development environment variables
|
||||
- `.env.staging` - Staging environment variables
|
||||
- `.env.production` - Production environment variables
|
||||
|
||||
### 2. Kubernetes Configuration
|
||||
|
||||
- `k8s-kustomize/overlays/{env}/config.env` - Kubernetes config for each environment
|
||||
- `k8s-kustomize/overlays/{env}/kustomization.yaml` - Updated kustomization files
|
||||
|
||||
### 3. Docker Configuration
|
||||
|
||||
- `docker/.env.{environment}` - Docker-specific environment files
|
||||
|
||||
### 4. Vite Configuration
|
||||
|
||||
- `.env.vite.{environment}` - Vite-specific variables
|
||||
|
||||
### 5. TypeScript Exports
|
||||
|
||||
- `config/generated/{environment}.config.ts` - Type-safe config exports
|
||||
|
||||
## Scripts
|
||||
|
||||
### Generation Scripts
|
||||
|
||||
```bash
|
||||
# Generate unified configuration
|
||||
bun scripts/generate-unified-config.ts
|
||||
|
||||
# Generate for specific environment
|
||||
bun scripts/generate-unified-config.ts production
|
||||
|
||||
# Generate for all environments
|
||||
bun scripts/generate-unified-config.ts --all
|
||||
|
||||
# Dry run (preview changes)
|
||||
bun scripts/generate-unified-config.ts --dry-run
|
||||
|
||||
# Verbose output
|
||||
bun scripts/generate-unified-config.ts --verbose
|
||||
```
|
||||
|
||||
### Migration Scripts
|
||||
|
||||
```bash
|
||||
# Migrate from old config system
|
||||
bun scripts/migrate-to-unified-config.ts
|
||||
|
||||
# Migration with backup
|
||||
bun scripts/migrate-to-unified-config.ts --backup
|
||||
|
||||
# Preview migration changes
|
||||
bun scripts/migrate-to-unified-config.ts --dry-run
|
||||
```
|
||||
|
||||
## Migration from Old System
|
||||
|
||||
If you're migrating from the old configuration system:
|
||||
|
||||
### 1. Backup Current Configuration
|
||||
|
||||
```bash
|
||||
bun scripts/migrate-to-unified-config.ts --backup
|
||||
```
|
||||
|
||||
### 2. Run Migration
|
||||
|
||||
```bash
|
||||
bun scripts/migrate-to-unified-config.ts
|
||||
```
|
||||
|
||||
### 3. Generate New Config Files
|
||||
|
||||
```bash
|
||||
make generate-config
|
||||
```
|
||||
|
||||
### 4. Test Application
|
||||
|
||||
```bash
|
||||
make dev
|
||||
```
|
||||
|
||||
### 5. Deploy
|
||||
|
||||
```bash
|
||||
make deploy-prod-quick
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Environment Variables
|
||||
|
||||
- Use `VITE_` prefix for frontend-accessible variables
|
||||
- Keep sensitive data in environment variables, not in code
|
||||
- Use meaningful defaults for non-sensitive configuration
|
||||
|
||||
### 2. Configuration Updates
|
||||
|
||||
- Always regenerate config files after changing unified config
|
||||
- Test configuration changes in development first
|
||||
- Use the validation features to catch issues early
|
||||
|
||||
### 3. Secrets Management
|
||||
|
||||
- Never commit secrets to version control
|
||||
- Use environment variables for all sensitive data
|
||||
- Consider using external secret management in production
|
||||
|
||||
### 4. Environment Consistency
|
||||
|
||||
- Keep environment-specific overrides minimal
|
||||
- Document any environment-specific requirements
|
||||
- Test deployments in staging before production
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Configuration Not Loading
|
||||
|
||||
1. Check that NODE_ENV is set correctly
|
||||
2. Verify environment variables are accessible
|
||||
3. Run `make config-debug` to see current configuration
|
||||
4. Check for TypeScript compilation errors
|
||||
|
||||
### Missing Environment Variables
|
||||
|
||||
1. Check if variables are defined in `.env` file
|
||||
2. Verify variable names match the expected format
|
||||
3. Use `make validate-config` to identify missing required variables
|
||||
|
||||
### Kubernetes Deployment Issues
|
||||
|
||||
1. Regenerate Kubernetes configs: `make generate-config-prod`
|
||||
2. Check that namespace exists: `kubectl get namespaces`
|
||||
3. Verify config maps: `kubectl get configmaps -n {namespace}`
|
||||
|
||||
### Build/Runtime Errors
|
||||
|
||||
1. Ensure all VITE\_ prefixed variables are available at build time
|
||||
2. Check Vite configuration for proper variable injection
|
||||
3. Verify TypeScript types are consistent
|
||||
|
||||
## Development
|
||||
|
||||
### Adding New Configuration
|
||||
|
||||
1. Update the `UnifiedConfig` interface in `unified.config.ts`
|
||||
2. Add default values to `defaultConfig`
|
||||
3. Add environment-specific overrides if needed
|
||||
4. Update environment variable loading in `loadFromEnvironment`
|
||||
5. Regenerate configuration files
|
||||
|
||||
### Adding New Environment
|
||||
|
||||
1. Add environment to `Environment` type
|
||||
2. Add environment-specific config to `environmentConfigs`
|
||||
3. Update generation scripts to handle new environment
|
||||
4. Create Kubernetes overlay directory structure
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- JWT secrets must be changed in production
|
||||
- Database passwords should be strong and unique
|
||||
- API keys should be rotated regularly
|
||||
- Use HTTPS in production environments
|
||||
- Enable security headers in production
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Cache timeouts should be appropriate for your use case
|
||||
- Resource limits should match your infrastructure
|
||||
- Monitor application performance in different environments
|
||||
- Adjust replica counts based on load requirements
|
||||
|
||||
## Support
|
||||
|
||||
For questions or issues with the unified configuration system:
|
||||
|
||||
1. Check this documentation first
|
||||
2. Run diagnostic commands (`make config-debug`, `make validate-config`)
|
||||
3. Review generated configuration files
|
||||
4. Check application logs for configuration-related errors
|
||||
|
||||
---
|
||||
|
||||
_This unified configuration system provides a robust, scalable, and maintainable approach to application configuration management._
|
||||
Reference in New Issue
Block a user