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,50 +1,21 @@
|
||||
# 📁 Project Structure
|
||||
|
||||
## Final Organized Structure
|
||||
## Current Development Structure
|
||||
|
||||
```
|
||||
rxminder/
|
||||
├── 📄 README.md # Main documentation
|
||||
├── package.json # Dependencies and scripts
|
||||
├── 📄 README.md # Main project documentation
|
||||
├── 📦 package.json # Dependencies and scripts
|
||||
├── ⚙️ vite.config.ts # Build configuration
|
||||
├── 📝 tsconfig.json # TypeScript configuration
|
||||
├── 🎨 index.html # Entry point
|
||||
├── 🎨 index.html # Generated entry point
|
||||
├── 🎨 index.html.template # Template for HTML generation
|
||||
├── 🔒 .env.example # Environment template
|
||||
├── 📊 metadata.json # Project metadata
|
||||
├── 🖼️ banner.jpeg # Project banner image
|
||||
│
|
||||
├── <EFBFBD> docker/ # Container configuration
|
||||
│ ├── 🐳 Dockerfile # Multi-stage Docker build
|
||||
│ ├── <20> docker-compose.yaml # Service orchestration
|
||||
│ ├── 🌐 nginx.conf # Production web server config
|
||||
│ └── 🚫 .dockerignore # Docker ignore patterns
|
||||
│
|
||||
├── 📁 scripts/ # All deployment and utility scripts
|
||||
│ ├── 🚀 deploy.sh # Production deployment
|
||||
│ ├── ⚡ deploy-k8s.sh # Kubernetes deployment
|
||||
│ ├── 🔧 setup.sh # Development setup
|
||||
│ ├── 🌱 seed-production.js # Database seeding
|
||||
│ ├── ✅ validate-env.sh # Environment validation
|
||||
│ └── 🧪 validate-deployment.sh # Deployment testing
|
||||
│
|
||||
├── 📁 tests/ # Testing infrastructure
|
||||
│ ├── 📝 README.md # Testing documentation
|
||||
│ ├── ⚙️ setup.ts # Jest configuration
|
||||
│ ├── 📁 integration/ # Integration tests
|
||||
│ │ └── 🧪 production.test.js # Production validation
|
||||
│ ├── 📁 manual/ # Manual testing scripts
|
||||
│ │ ├── 🔧 admin-login-debug.js # Admin debugging
|
||||
│ │ ├── 🔧 auth-db-debug.js # Auth debugging
|
||||
│ │ └── 🔧 debug-email-validation.js # Email debugging
|
||||
│ └── 📁 e2e/ # End-to-end tests with Playwright
|
||||
│ ├── 📝 README.md # E2E testing documentation
|
||||
│ ├── 🧪 fixtures.ts # Custom test fixtures
|
||||
│ ├── 🧪 helpers.ts # Test utilities and data
|
||||
│ ├── 🧪 auth.spec.ts # Authentication flow tests
|
||||
│ ├── 🧪 medication.spec.ts # Medication management tests
|
||||
│ ├── 🧪 admin.spec.ts # Admin interface tests
|
||||
│ ├── 🧪 ui-navigation.spec.ts # UI and navigation tests
|
||||
│ └── 🧪 reminders.spec.ts # Reminder system tests
|
||||
├── 🚀 index.tsx # React application entry point
|
||||
├── 🎯 App.tsx # Main React component
|
||||
├── 📋 types.ts # Global type definitions
|
||||
│
|
||||
├── 📁 components/ # React components (organized by feature)
|
||||
│ ├── 📝 README.md # Component architecture docs
|
||||
@@ -81,102 +52,293 @@ rxminder/
|
||||
│
|
||||
├── 📁 services/ # Business logic & APIs
|
||||
│ ├── 🗄️ database/ # Unified database service
|
||||
│ │ ├── DatabaseService.ts # Main service with strategy pattern
|
||||
│ │ ├── MockDatabaseStrategy.ts # In-memory implementation
|
||||
│ │ ├── ProductionDatabaseStrategy.ts # CouchDB implementation
|
||||
│ │ └── types.ts # Database interfaces
|
||||
│ │ ├── 📋 DatabaseService.ts # Main service with strategy pattern
|
||||
│ │ ├── 🧪 MockDatabaseStrategy.ts # In-memory implementation
|
||||
│ │ ├── 🏭 ProductionDatabaseStrategy.ts # CouchDB implementation
|
||||
│ │ ├── 📝 types.ts # Database interfaces
|
||||
│ │ ├── 📦 index.ts # Public exports
|
||||
│ │ └── 📝 README.md # Database service documentation
|
||||
│ ├── 📧 logging/ # Centralized logging system
|
||||
│ │ ├── 📊 Logger.ts # Main logger implementation
|
||||
│ │ └── 📦 index.ts # Public exports
|
||||
│ ├── 📧 email.ts # Email utilities
|
||||
│ ├── 📧 mailgun.service.ts # Email delivery
|
||||
│ ├── 📧 mailgun.config.ts # Email configuration
|
||||
│ ├── 🌱 database.seeder.ts # Data seeding
|
||||
│ ├── 🔐 oauth.ts # OAuth integration
|
||||
│ └── 📁 auth/ # Authentication services
|
||||
│ ├── 🔐 auth.service.ts # Core auth logic
|
||||
│ ├── 🔐 auth.types.ts # Auth type definitions
|
||||
│ ├── 🔐 auth.constants.ts # Auth constants
|
||||
│ ├── 🔐 auth.error.ts # Error handling
|
||||
│ ├── 🔐 auth.middleware.ts # Middleware
|
||||
│ ├── 📧 mailgun.service.ts # Email delivery
|
||||
│ ├── 📧 mailgun.config.ts # Email configuration
|
||||
│ ├── 🌱 database.seeder.ts # Data seeding
|
||||
│ ├── 🔐 oauth.ts # OAuth integration
|
||||
│ └── 📁 auth/ # Authentication services
|
||||
│ ├── 🔐 auth.service.ts # Core auth logic
|
||||
│ ├── 📝 auth.types.ts # Auth type definitions
|
||||
│ ├── 📋 auth.constants.ts # Auth constants
|
||||
│ ├── ⚠️ auth.error.ts # Error handling
|
||||
│ ├── 🛡️ auth.middleware.ts # Middleware
|
||||
│ ├── ✉️ emailVerification.service.ts
|
||||
│ ├── 📁 templates/ # Email templates
|
||||
│ ├── 📁 templates/ # Email templates
|
||||
│ │ └── ✉️ verification.email.ts
|
||||
│ └── 📁 __tests__/ # Unit tests
|
||||
│ └── 📁 __tests__/ # Unit tests
|
||||
│ ├── 🧪 auth.integration.test.ts
|
||||
│ └── 🧪 emailVerification.test.ts
|
||||
│
|
||||
├── 📁 config/ # Configuration management
|
||||
│ └── ⚙️ unified.config.ts # Centralized configuration with validation
|
||||
│
|
||||
├── 📁 contexts/ # React context providers
|
||||
│ └── 👤 UserContext.tsx # User state management
|
||||
│ └── 👤 UserContext.tsx # User state management
|
||||
│
|
||||
├── 📁 hooks/ # Custom React hooks
|
||||
│ ├── 💾 useLocalStorage.ts # Persistent storage
|
||||
│ ├── ⚙️ useSettings.ts # User preferences
|
||||
│ ├── 🎨 useTheme.ts # Theme management
|
||||
│ └── 👤 useUserData.ts # User data management
|
||||
│ ├── 💾 useLocalStorage.ts # Persistent storage
|
||||
│ ├── ⚙️ useSettings.ts # User preferences
|
||||
│ ├── 🎨 useTheme.ts # Theme management
|
||||
│ └── 👤 useUserData.ts # User data management
|
||||
│
|
||||
├── 📁 utils/ # Utility functions
|
||||
│ └── ⏰ schedule.ts # Reminder scheduling
|
||||
│ └── ⏰ schedule.ts # Reminder scheduling
|
||||
│
|
||||
├── 📁 types/ # TypeScript type definitions
|
||||
│ └── 📝 index.ts # Global type exports
|
||||
│
|
||||
├── 📁 scripts/ # Development and build scripts
|
||||
│ ├── 🔧 setup.sh # Development setup
|
||||
│ ├── 🎨 process-html.sh # HTML template processing
|
||||
│ ├── 🧹 setup-pre-commit.sh # Git hooks setup
|
||||
│ └── 🌱 seed-production.js # Database seeding
|
||||
│
|
||||
├── 📁 tests/ # Testing infrastructure
|
||||
│ ├── 📝 README.md # Testing documentation
|
||||
│ ├── ⚙️ setup.ts # Jest configuration
|
||||
│ ├── 📁 integration/ # Integration tests
|
||||
│ │ └── 🧪 production.test.js # Production validation
|
||||
│ ├── 📁 manual/ # Manual testing scripts
|
||||
│ │ ├── 🔧 admin-login-debug.js # Admin debugging
|
||||
│ │ ├── 🔧 auth-db-debug.js # Auth debugging
|
||||
│ │ └── 🔧 debug-email-validation.js # Email debugging
|
||||
│ └── 📁 e2e/ # End-to-end tests with Playwright
|
||||
│ ├── 📝 README.md # E2E testing documentation
|
||||
│ ├── 🧪 fixtures.ts # Custom test fixtures
|
||||
│ ├── 🧪 helpers.ts # Test utilities and data
|
||||
│ ├── 🧪 auth.spec.ts # Authentication flow tests
|
||||
│ ├── 🧪 medication.spec.ts # Medication management tests
|
||||
│ ├── 🧪 admin.spec.ts # Admin interface tests
|
||||
│ ├── 🧪 ui-navigation.spec.ts # UI and navigation tests
|
||||
│ └── 🧪 reminders.spec.ts # Reminder system tests
|
||||
│
|
||||
├── 📁 docs/ # Project documentation
|
||||
│ ├── 🔐 SECURITY.md # Security guidelines
|
||||
│ ├── 🚀 DEPLOYMENT.md # Deployment instructions
|
||||
│ └── 📖 API.md # API documentation
|
||||
│ ├── 📋 README.md # Documentation index
|
||||
│ ├── 📁 architecture/ # Design & Architecture
|
||||
│ │ ├── 🏗️ PROJECT_STRUCTURE.md # This file
|
||||
│ │ └── 🎯 TEMPLATE_APPROACH.md # Configuration approach
|
||||
│ ├── 📁 setup/ # Setup & Configuration
|
||||
│ │ ├── ⚙️ COMPLETE_TEMPLATE_CONFIGURATION.md
|
||||
│ │ ├── ✅ SETUP_COMPLETE.md
|
||||
│ │ ├── 🌍 ENVIRONMENT_VARIABLES.md
|
||||
│ │ └── 🏷️ APP_NAME_CONFIGURATION.md
|
||||
│ ├── 📁 development/ # Development Guides
|
||||
│ │ ├── 📖 API.md # API documentation
|
||||
│ │ ├── 🗄️ DATABASE.md # Database service docs
|
||||
│ │ ├── ✨ CODE_QUALITY.md # Quality standards
|
||||
│ │ ├── 🔒 APPLICATION_SECURITY.md # Security practices
|
||||
│ │ ├── 🔄 SECURITY_CHANGES.md # Security updates
|
||||
│ │ └── 🪝 PRE_COMMIT_HOOKS.md # Git hook configuration
|
||||
│ └── 📁 implementation/ # Current Status
|
||||
│ └── 📊 IMPLEMENTATION_SUMMARY.md
|
||||
│
|
||||
├── 📁 k8s/ # Kubernetes manifests
|
||||
│ ├── 📝 README.md # K8s deployment guide
|
||||
│ ├── 🗺️ configmap.yaml # Configuration
|
||||
│ ├── 🔒 *-secret.yaml # Secrets
|
||||
│ ├── 🚀 *-deployment.yaml # Deployments
|
||||
│ ├── 🌐 *-service.yaml # Services
|
||||
│ ├── 📊 hpa.yaml # Auto-scaling
|
||||
│ ├── 🌐 ingress.yaml # Load balancing
|
||||
│ └── 🔒 network-policy.yaml # Network security
|
||||
├── 📁 coverage/ # Test coverage reports
|
||||
├── 📁 dist/ # Production build output
|
||||
├── 📁 node_modules/ # Dependencies
|
||||
│
|
||||
└── 📁 .github/ # GitHub configuration
|
||||
├── 📝 pull_request_template.md
|
||||
└── 📁 ISSUE_TEMPLATE/
|
||||
├── 🐛 bug_report.md
|
||||
└── ✨ feature_request.md
|
||||
└── 📁 Configuration Files # Development configuration
|
||||
├── 🔧 .gitignore # Git ignore patterns
|
||||
├── 🎨 .prettierrc # Code formatting rules
|
||||
├── ⚡ eslint.config.cjs # Linting configuration
|
||||
├── 🧪 jest.config.json # Test configuration
|
||||
├── 🎭 playwright.config.ts # E2E test configuration
|
||||
├── 📝 .markdownlint.json # Markdown linting
|
||||
├── 🔒 .secretlintrc.json # Secret detection
|
||||
├── ✏️ .editorconfig # Editor consistency
|
||||
├── 🪝 .husky/ # Git hooks
|
||||
└── 📄 Various other config files
|
||||
```
|
||||
|
||||
## Key Organizational Principles
|
||||
|
||||
### ✅ **Feature-Based Organization**
|
||||
### ✅ **Feature-Based Component Organization**
|
||||
|
||||
Components are organized by functionality rather than by type:
|
||||
|
||||
```
|
||||
components/
|
||||
├── medication/ # All medication-related UI
|
||||
├── auth/ # Authentication components
|
||||
├── admin/ # Admin interface
|
||||
├── modals/ # Modal dialogs
|
||||
└── ui/ # Reusable UI components
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Related functionality stays together
|
||||
- Easy to find and modify features
|
||||
- Clear boundaries between different parts of the app
|
||||
- Scalable as features grow
|
||||
|
||||
### ✅ **Service Layer Architecture**
|
||||
|
||||
Services provide business logic separate from UI components:
|
||||
|
||||
```
|
||||
services/
|
||||
├── database/ # Data persistence with strategy pattern
|
||||
├── logging/ # Centralized logging system
|
||||
└── auth/ # Authentication and user management
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Components grouped by functionality (medication, auth, admin, etc.)
|
||||
- Clear separation of concerns
|
||||
- Easy to locate related files
|
||||
|
||||
### ✅ **Script Centralization**
|
||||
|
||||
- All deployment and utility scripts in `/scripts/`
|
||||
- Consistent naming conventions
|
||||
- Easy access via npm/bun scripts
|
||||
|
||||
### ✅ **Testing Structure**
|
||||
|
||||
- Unit tests alongside source code (`services/auth/__tests__/`)
|
||||
- Integration tests in `/tests/integration/`
|
||||
- E2E tests with Playwright in `/tests/e2e/`
|
||||
- Manual debugging tools in `/tests/manual/`
|
||||
- Comprehensive test documentation
|
||||
- TypeScript support with temporary type declarations
|
||||
|
||||
### ✅ **Documentation Organization**
|
||||
|
||||
- Feature-specific READMEs in relevant folders
|
||||
- Centralized docs in `/docs/` folder
|
||||
- Clear architectural documentation
|
||||
- Reusable business logic
|
||||
- Easy to test and mock
|
||||
- Strategy pattern allows flexible implementations
|
||||
|
||||
### ✅ **Configuration Management**
|
||||
|
||||
- Environment files at root level
|
||||
- Build configurations easily accessible
|
||||
- Docker and K8s configs clearly separated
|
||||
Centralized configuration with environment-based templates:
|
||||
|
||||
## Benefits
|
||||
```
|
||||
config/
|
||||
└── unified.config.ts # Single source of truth
|
||||
|
||||
🎯 **Maintainability** - Clear structure makes code easy to maintain
|
||||
🔍 **Discoverability** - Logical organization helps find files quickly
|
||||
🧪 **Testability** - Well-organized test structure
|
||||
📦 **Deployability** - Scripts and configs clearly separated
|
||||
# Template approach
|
||||
index.html.template → index.html # Processed with environment variables
|
||||
.env.example → .env # User customization
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- No hardcoded configuration
|
||||
- Environment-specific settings
|
||||
- Type-safe configuration access
|
||||
- Clear separation of config and code
|
||||
|
||||
### ✅ **Testing Strategy**
|
||||
|
||||
Comprehensive testing at multiple levels:
|
||||
|
||||
```
|
||||
tests/
|
||||
├── integration/ # Service integration tests
|
||||
├── manual/ # Debug scripts and manual testing
|
||||
└── e2e/ # Full application testing
|
||||
|
||||
# Unit tests alongside code
|
||||
services/auth/__tests__/ # Co-located with services
|
||||
components/__tests__/ # Component-specific tests
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Tests close to the code they test
|
||||
- Multiple testing strategies
|
||||
- Easy to run specific test suites
|
||||
- Clear separation of test types
|
||||
|
||||
### ✅ **Documentation Structure**
|
||||
|
||||
Documentation organized by purpose and audience:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── architecture/ # System design and patterns
|
||||
├── setup/ # Configuration and installation
|
||||
├── development/ # Developer guides and APIs
|
||||
└── implementation/ # Current status and features
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Easy navigation by role (developer, ops, etc.)
|
||||
- Clear separation of different doc types
|
||||
- Comprehensive coverage of all aspects
|
||||
- Living documentation that stays current
|
||||
|
||||
## 🎯 Development Workflow
|
||||
|
||||
### Local Development Setup
|
||||
|
||||
1. **Environment Configuration**
|
||||
|
||||
```bash
|
||||
cp .env.example .env # Copy template
|
||||
nano .env # Customize settings
|
||||
```
|
||||
|
||||
2. **Template Processing**
|
||||
|
||||
```bash
|
||||
bun run predev # Process HTML templates
|
||||
bun run dev # Start development server
|
||||
```
|
||||
|
||||
3. **Code Quality**
|
||||
```bash
|
||||
bun run lint # Check code quality
|
||||
bun run format # Format code
|
||||
bun run type-check # TypeScript validation
|
||||
```
|
||||
|
||||
### Database Strategy Selection
|
||||
|
||||
The application automatically selects the appropriate database strategy:
|
||||
|
||||
- **Development**: Mock database (instant responses, no setup)
|
||||
- **Testing**: Mock database (isolated test data)
|
||||
- **Production**: CouchDB (persistent storage)
|
||||
|
||||
### Component Development
|
||||
|
||||
1. **Create feature-based components** in appropriate folders
|
||||
2. **Export from index.ts** for clean imports
|
||||
3. **Co-locate tests** with components when appropriate
|
||||
4. **Use TypeScript** for type safety
|
||||
|
||||
### Service Development
|
||||
|
||||
1. **Implement business logic** in service layer
|
||||
2. **Use dependency injection** for testability
|
||||
3. **Follow strategy pattern** for flexibility
|
||||
4. **Add comprehensive tests** for reliability
|
||||
|
||||
## 📊 Metrics and Standards
|
||||
|
||||
### Code Organization
|
||||
|
||||
- **Feature cohesion**: Related code stays together
|
||||
- **Clear boundaries**: Services, components, utilities clearly separated
|
||||
- **Consistent patterns**: Similar organization across features
|
||||
- **Scalable structure**: Easy to add new features without reorganization
|
||||
|
||||
### Development Experience
|
||||
|
||||
- **Fast setup**: One command to get started
|
||||
- **Quick iteration**: Hot reloading and instant feedback
|
||||
- **Easy testing**: Multiple test strategies available
|
||||
- **Clear debugging**: Structured logging and debug tools
|
||||
|
||||
### Maintainability
|
||||
|
||||
- **Self-documenting**: Clear folder structure and naming
|
||||
- **Consistent patterns**: Similar approaches across the codebase
|
||||
- **Easy refactoring**: Loose coupling between components
|
||||
- **Future-proof**: Architecture supports growth and changes
|
||||
|
||||
## 🚀 Benefits
|
||||
|
||||
🎯 **Discoverability** - Logical structure makes files easy to find
|
||||
🔧 **Maintainability** - Clear patterns make code easy to modify
|
||||
🧪 **Testability** - Well-organized test structure and strategy
|
||||
📈 **Scalability** - Architecture supports feature growth
|
||||
👥 **Team Collaboration** - Consistent patterns across the project
|
||||
📈 **Scalability** - Structure supports growth and new features
|
||||
🛡️ **Reliability** - Strategy pattern provides flexibility and fallbacks
|
||||
⚡ **Performance** - Optimized development and build processes
|
||||
📚 **Documentation** - Comprehensive guides for all aspects
|
||||
|
||||
This structure provides a solid foundation for continued development and future enhancements while maintaining code quality and developer productivity.
|
||||
|
||||
@@ -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