f51bdeb284
- Update TEMPLATE_APPROACH.md from Kubernetes deployment to development configuration - Update PROJECT_STRUCTURE.md to reflect current development structure - Remove references to non-existent deployment artifacts - Focus on environment-based configuration and template processing - Document actual current features rather than future deployment scenarios
279 lines
7.4 KiB
Markdown
279 lines
7.4 KiB
Markdown
# 🎯 Template-Based Configuration Approach
|
|
|
|
## Overview
|
|
|
|
RxMinder uses a **template-based configuration approach** with environment variables to provide flexible, secure, and maintainable configuration management across different environments.
|
|
|
|
## 🆚 Configuration Philosophy
|
|
|
|
### ❌ Before (Hardcoded Values)
|
|
|
|
**Old approach with hardcoded configuration:**
|
|
|
|
```typescript
|
|
// Hardcoded configuration
|
|
const config = {
|
|
appName: 'RxMinder',
|
|
baseUrl: 'http://localhost:5173',
|
|
dbUrl: 'http://localhost:5984',
|
|
adminPassword: 'admin123', // ❌ Security risk
|
|
};
|
|
```
|
|
|
|
**Problems:**
|
|
|
|
- 😣 No environment flexibility
|
|
- 🔧 Configuration changes require code changes
|
|
- 📝 Hard to customize for different deployments
|
|
- 🔒 Security risks with hardcoded credentials
|
|
|
|
### ✅ After (Template-Based)
|
|
|
|
**New approach uses environment variables with templates:**
|
|
|
|
```typescript
|
|
// Environment-based configuration
|
|
const config = {
|
|
appName: process.env.VITE_APP_NAME || 'RxMinder',
|
|
baseUrl: process.env.VITE_BASE_URL || 'http://localhost:5173',
|
|
dbUrl: process.env.VITE_COUCHDB_URL || 'http://localhost:5984',
|
|
adminPassword: process.env.VITE_COUCHDB_PASSWORD, // ✅ Secure
|
|
};
|
|
```
|
|
|
|
**Benefits:**
|
|
|
|
- ✅ Environment-specific configuration
|
|
- ✅ No hardcoded secrets in code
|
|
- ✅ Easy customization via `.env` files
|
|
- ✅ Template processing for HTML and other assets
|
|
- ✅ Type-safe configuration with validation
|
|
|
|
## 🚀 How It Works
|
|
|
|
### 1. Environment Configuration
|
|
|
|
```bash
|
|
# .env.example (template for all environments)
|
|
VITE_APP_NAME=RxMinder
|
|
VITE_BASE_URL=http://localhost:5173
|
|
VITE_COUCHDB_URL=http://localhost:5984
|
|
VITE_COUCHDB_USER=admin
|
|
VITE_COUCHDB_PASSWORD=secure-password-123
|
|
|
|
# Email configuration (optional)
|
|
VITE_MAILGUN_API_KEY=your-mailgun-api-key
|
|
VITE_MAILGUN_DOMAIN=your-domain.com
|
|
|
|
# OAuth configuration (optional)
|
|
VITE_GOOGLE_CLIENT_ID=your-google-client-id
|
|
VITE_GITHUB_CLIENT_ID=your-github-client-id
|
|
|
|
# Feature flags
|
|
ENABLE_EMAIL_VERIFICATION=true
|
|
ENABLE_OAUTH=true
|
|
DEBUG_MODE=false
|
|
```
|
|
|
|
### 2. Template Processing
|
|
|
|
#### HTML Template Processing
|
|
|
|
```html
|
|
<!-- index.html.template -->
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<title>${APP_NAME}</title>
|
|
<meta name="description" content="${APP_NAME} - Medication Reminder App" />
|
|
</head>
|
|
</html>
|
|
```
|
|
|
|
**Processed to:**
|
|
|
|
```html
|
|
<!-- index.html -->
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<title>MyCustomApp</title>
|
|
<meta name="description" content="MyCustomApp - Medication Reminder App" />
|
|
</head>
|
|
</html>
|
|
```
|
|
|
|
#### Configuration Template
|
|
|
|
```typescript
|
|
// config/unified.config.ts (centralized configuration)
|
|
export const unifiedConfig = {
|
|
app: {
|
|
name: import.meta.env.VITE_APP_NAME || 'RxMinder',
|
|
environment: import.meta.env.NODE_ENV || 'development',
|
|
baseUrl: import.meta.env.VITE_BASE_URL || 'http://localhost:5173',
|
|
version: import.meta.env.VITE_APP_VERSION || '0.0.0',
|
|
},
|
|
database: {
|
|
url: import.meta.env.VITE_COUCHDB_URL || 'http://localhost:5984',
|
|
username: import.meta.env.VITE_COUCHDB_USER || 'admin',
|
|
password: import.meta.env.VITE_COUCHDB_PASSWORD || '',
|
|
},
|
|
features: {
|
|
emailVerification: import.meta.env.ENABLE_EMAIL_VERIFICATION === 'true',
|
|
oauth: import.meta.env.ENABLE_OAUTH === 'true',
|
|
debug: import.meta.env.DEBUG_MODE === 'true',
|
|
},
|
|
};
|
|
```
|
|
|
|
### 3. Development vs Production
|
|
|
|
#### Development Environment
|
|
|
|
```bash
|
|
# .env (development)
|
|
VITE_APP_NAME=RxMinder-Dev
|
|
VITE_COUCHDB_URL=http://localhost:5984
|
|
DEBUG_MODE=true
|
|
ENABLE_EMAIL_VERIFICATION=false
|
|
```
|
|
|
|
#### Production Environment
|
|
|
|
```bash
|
|
# .env.production
|
|
VITE_APP_NAME=MedicationTracker
|
|
VITE_COUCHDB_URL=https://your-couchdb.com
|
|
ENABLE_EMAIL_VERIFICATION=true
|
|
ENABLE_OAUTH=true
|
|
DEBUG_MODE=false
|
|
```
|
|
|
|
## 🔧 Template Files in Project
|
|
|
|
### 1. HTML Templates
|
|
|
|
- **`index.html.template`** - Main HTML entry point with variable substitution
|
|
- **`index.html`** - Generated file (processed by `scripts/process-html.sh`)
|
|
|
|
### 2. Configuration Templates
|
|
|
|
- **`.env.example`** - Template for environment configuration
|
|
- **`config/unified.config.ts`** - Centralized configuration with validation
|
|
|
|
### 3. Processing Scripts
|
|
|
|
- **`scripts/process-html.sh`** - HTML template processing
|
|
- **`package.json`** - Scripts for template processing (`predev`, `prebuild`)
|
|
|
|
## 🛡️ Security Benefits
|
|
|
|
### Environment Separation
|
|
|
|
- **Development**: Uses mock data and relaxed security
|
|
- **Production**: Requires all security features and real credentials
|
|
- **Clear boundaries** between environments
|
|
|
|
### Credential Management
|
|
|
|
- **No secrets in code** - All sensitive data in environment variables
|
|
- **Environment-specific secrets** - Different credentials per environment
|
|
- **Template validation** - Ensures required variables are set
|
|
|
|
### Configuration Validation
|
|
|
|
```typescript
|
|
// Automatic validation in unified.config.ts
|
|
if (!unifiedConfig.database.password && unifiedConfig.app.environment === 'production') {
|
|
throw new Error('Database password is required in production');
|
|
}
|
|
```
|
|
|
|
## 📝 Development Workflow
|
|
|
|
### 1. Initial Setup
|
|
|
|
```bash
|
|
# Copy template
|
|
cp .env.example .env
|
|
|
|
# Customize for your environment
|
|
nano .env
|
|
|
|
# Process templates
|
|
bun run predev
|
|
```
|
|
|
|
### 2. Development
|
|
|
|
```bash
|
|
# Start with template processing
|
|
bun run dev # Automatically runs predev
|
|
|
|
# Templates are processed automatically
|
|
# HTML title updates based on APP_NAME
|
|
# Configuration updates based on environment variables
|
|
```
|
|
|
|
### 3. Building
|
|
|
|
```bash
|
|
# Production build with template processing
|
|
bun run build # Automatically runs prebuild
|
|
|
|
# Templates processed for production
|
|
# Environment variables baked into build
|
|
```
|
|
|
|
## 🎯 Benefits
|
|
|
|
### For Developers
|
|
|
|
| Aspect | Before | After |
|
|
| ----------------- | ------------------- | ------------------------- |
|
|
| **Setup** | Manual file editing | Copy `.env.example` |
|
|
| **Customization** | Code changes | Environment variables |
|
|
| **Testing** | Hardcoded test data | Environment-based mocking |
|
|
| **Debugging** | Console hunting | Centralized debug flags |
|
|
|
|
### For Operations
|
|
|
|
| Aspect | Before | After |
|
|
| -------------- | -------------------- | ---------------------- |
|
|
| **Deployment** | Manual configuration | Environment-based |
|
|
| **Security** | Hardcoded secrets | External configuration |
|
|
| **Monitoring** | Scattered settings | Centralized config |
|
|
| **Scaling** | Per-instance setup | Template replication |
|
|
|
|
## 🔍 Best Practices
|
|
|
|
### Environment Variable Naming
|
|
|
|
- Use `VITE_` prefix for client-side variables
|
|
- Use descriptive names (`VITE_COUCHDB_PASSWORD` vs `PASSWORD`)
|
|
- Group related variables (`VITE_MAILGUN_API_KEY`, `VITE_MAILGUN_DOMAIN`)
|
|
|
|
### Template Organization
|
|
|
|
- Keep templates close to generated files
|
|
- Use clear naming conventions (`.template` suffix)
|
|
- Document all template variables
|
|
|
|
### Validation Strategy
|
|
|
|
- Validate required variables at startup
|
|
- Provide clear error messages for missing configuration
|
|
- Use TypeScript for compile-time validation
|
|
|
|
## 🚀 Result
|
|
|
|
The template-based approach makes RxMinder configuration:
|
|
|
|
- **More flexible** - Easy customization for different environments
|
|
- **More secure** - No hardcoded secrets in source code
|
|
- **More maintainable** - Centralized configuration management
|
|
- **More scalable** - Template-driven deployment processes
|
|
|
|
This approach follows modern application configuration best practices and provides a solid foundation for development, testing, and future deployment needs.
|