From 8c8cea9e4211895f63fa38b40e9fb2fc57371711 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 8 Sep 2025 09:44:33 -0700 Subject: [PATCH] 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 --- config/README.md | 411 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 411 insertions(+) create mode 100644 config/README.md diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..b7d27d9 --- /dev/null +++ b/config/README.md @@ -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._