docs: refocus architecture docs on current development state
- 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
This commit is contained in:
William Valentin
@@ -1,159 +1,278 @@
|
||||
# 🎯 Template-Based Kubernetes Configuration
|
||||
# 🎯 Template-Based Configuration Approach
|
||||
|
||||
## Overview
|
||||
|
||||
We've implemented a **template-based approach** using environment variables instead of manual base64 encoding for Kubernetes secrets. This is much more user-friendly and secure.
|
||||
RxMinder uses a **template-based configuration approach** with environment variables to provide flexible, secure, and maintainable configuration management across different environments.
|
||||
|
||||
## 🆚 Before vs After Comparison
|
||||
## 🆚 Configuration Philosophy
|
||||
|
||||
### ❌ Before (Manual Base64 Encoding)
|
||||
### ❌ Before (Hardcoded Values)
|
||||
|
||||
**Old approach required manual base64 encoding:**
|
||||
**Old approach with hardcoded configuration:**
|
||||
|
||||
```yaml
|
||||
# k8s/couchdb-secret.yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
data:
|
||||
# User had to manually encode:
|
||||
# echo -n "admin" | base64 -> YWRtaW4=
|
||||
# echo -n "password" | base64 -> cGFzc3dvcmQ=
|
||||
username: YWRtaW4=
|
||||
password: cGFzc3dvcmQ=
|
||||
```typescript
|
||||
// Hardcoded configuration
|
||||
const config = {
|
||||
appName: 'RxMinder',
|
||||
baseUrl: 'http://localhost:5173',
|
||||
dbUrl: 'http://localhost:5984',
|
||||
adminPassword: 'admin123', // ❌ Security risk
|
||||
};
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
|
||||
- 😣 Manual base64 encoding required
|
||||
- 🔧 Error-prone (encoding mistakes)
|
||||
- 📝 Hard to read/verify credentials
|
||||
- 🔒 Credentials visible in YAML files
|
||||
- 😣 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 templates with automatic substitution:**
|
||||
**New approach uses environment variables with templates:**
|
||||
|
||||
```yaml
|
||||
# k8s/couchdb-secret.yaml.template
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: couchdb-secret
|
||||
labels:
|
||||
app: ${APP_NAME}
|
||||
type: Opaque
|
||||
stringData:
|
||||
# Kubernetes automatically base64 encodes stringData
|
||||
username: ${COUCHDB_USER}
|
||||
password: ${COUCHDB_PASSWORD}
|
||||
```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:**
|
||||
|
||||
- ✅ No manual base64 encoding needed
|
||||
- ✅ Environment variables from `.env` file
|
||||
- ✅ Human-readable configuration
|
||||
- ✅ Automatic deployment script
|
||||
- ✅ Customizable app names
|
||||
- ✅ 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. Configuration in `.env`
|
||||
### 1. Environment Configuration
|
||||
|
||||
```bash
|
||||
# .env (user-friendly configuration)
|
||||
APP_NAME=my-rxminder
|
||||
COUCHDB_USER=admin
|
||||
COUCHDB_PASSWORD=super-secure-password-123
|
||||
INGRESS_HOST=rxminder.mydomain.com
|
||||
# .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 Substitution
|
||||
### 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
|
||||
# Automatic substitution with envsubst
|
||||
envsubst < k8s/couchdb-secret.yaml.template
|
||||
# .env (development)
|
||||
VITE_APP_NAME=RxMinder-Dev
|
||||
VITE_COUCHDB_URL=http://localhost:5984
|
||||
DEBUG_MODE=true
|
||||
ENABLE_EMAIL_VERIFICATION=false
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: couchdb-secret
|
||||
labels:
|
||||
app: my-rxminder
|
||||
type: Opaque
|
||||
stringData:
|
||||
username: admin
|
||||
password: super-secure-password-123
|
||||
```
|
||||
|
||||
### 3. Kubernetes Processing
|
||||
|
||||
- Kubernetes automatically base64 encodes `stringData` fields
|
||||
- No manual encoding required
|
||||
- More secure and reliable
|
||||
|
||||
## 🎛️ Deployment Options
|
||||
|
||||
### Option 1: Automated Script (Recommended)
|
||||
#### Production Environment
|
||||
|
||||
```bash
|
||||
# Copy and configure
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
|
||||
# Deploy everything
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
# .env.production
|
||||
VITE_APP_NAME=MedicationTracker
|
||||
VITE_COUCHDB_URL=https://your-couchdb.com
|
||||
ENABLE_EMAIL_VERIFICATION=true
|
||||
ENABLE_OAUTH=true
|
||||
DEBUG_MODE=false
|
||||
```
|
||||
|
||||
### Option 2: Manual Template Processing
|
||||
## 🔧 Template Files in Project
|
||||
|
||||
```bash
|
||||
# Set environment variables
|
||||
export APP_NAME=my-rxminder
|
||||
export COUCHDB_PASSWORD=secure-password
|
||||
### 1. HTML Templates
|
||||
|
||||
# Process templates
|
||||
envsubst < k8s/couchdb-secret.yaml.template | kubectl apply -f -
|
||||
envsubst < k8s/ingress.yaml.template | kubectl apply -f -
|
||||
```
|
||||
- **`index.html.template`** - Main HTML entry point with variable substitution
|
||||
- **`index.html`** - Generated file (processed by `scripts/process-html.sh`)
|
||||
|
||||
## 🔧 Template Files Created
|
||||
### 2. Configuration Templates
|
||||
|
||||
1. **`k8s/couchdb-secret.yaml.template`** - Database credentials
|
||||
2. **`k8s/ingress.yaml.template`** - Ingress with custom hostname
|
||||
3. **`k8s/configmap.yaml.template`** - Application configuration
|
||||
4. **`k8s/frontend-deployment.yaml.template`** - Frontend deployment
|
||||
5. **`scripts/k8s-deploy-template.sh`** - Automated deployment script
|
||||
- **`.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
|
||||
|
||||
- **No hardcoded credentials** in version control
|
||||
- **Environment-specific configuration** via `.env` files
|
||||
- **Automatic validation** of required variables
|
||||
- **Kubernetes stringData** (auto base64 encoding)
|
||||
- **Clear separation** of config and code
|
||||
### Environment Separation
|
||||
|
||||
## 📝 User Experience Improvements
|
||||
- **Development**: Uses mock data and relaxed security
|
||||
- **Production**: Requires all security features and real credentials
|
||||
- **Clear boundaries** between environments
|
||||
|
||||
| Aspect | Before | After |
|
||||
| -------------------- | ------------------------ | ---------------------- |
|
||||
| **Setup Complexity** | High (manual base64) | Low (edit .env) |
|
||||
| **Error Rate** | High (encoding mistakes) | Low (plain text) |
|
||||
| **Readability** | Poor (base64 strings) | Excellent (plain text) |
|
||||
| **Customization** | Manual file editing | Environment variables |
|
||||
| **Deployment** | Multi-step manual | Single command |
|
||||
### Credential Management
|
||||
|
||||
## 🎯 Result
|
||||
- **No secrets in code** - All sensitive data in environment variables
|
||||
- **Environment-specific secrets** - Different credentials per environment
|
||||
- **Template validation** - Ensures required variables are set
|
||||
|
||||
The template-based approach makes RxMinder deployment:
|
||||
### Configuration Validation
|
||||
|
||||
- **More user-friendly** - No technical encoding required
|
||||
- **More secure** - Credentials externalized to `.env`
|
||||
- **More maintainable** - Clear separation of config and manifests
|
||||
- **More flexible** - Easy customization via environment variables
|
||||
```typescript
|
||||
// Automatic validation in unified.config.ts
|
||||
if (!unifiedConfig.database.password && unifiedConfig.app.environment === 'production') {
|
||||
throw new Error('Database password is required in production');
|
||||
}
|
||||
```
|
||||
|
||||
This is a **production-ready, enterprise-grade** configuration management approach that follows Kubernetes best practices.
|
||||
## 📝 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.
|
||||
|
||||
Reference in New Issue
Block a user