Initial commit: Complete NodeJS-native setup
- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
This commit is contained in:
William Valentin
319
docs/setup/COMPLETE_TEMPLATE_CONFIGURATION.md
Normal file
319
docs/setup/COMPLETE_TEMPLATE_CONFIGURATION.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 🎯 Complete Template-Based Configuration Summary
|
||||
|
||||
## Overview
|
||||
|
||||
RxMinder now supports **complete template-based configuration** with environment variables for all aspects of deployment, making it truly portable and customizable across any environment.
|
||||
|
||||
## 🔧 Configuration Variables
|
||||
|
||||
### Core Application
|
||||
|
||||
- **`APP_NAME`** - Application name used in all Kubernetes resources
|
||||
- **`DOCKER_IMAGE`** - Container image to deploy
|
||||
- **`INGRESS_HOST`** - External hostname for ingress
|
||||
|
||||
### Database Configuration
|
||||
|
||||
- **`COUCHDB_USER`** - Database username
|
||||
- **`COUCHDB_PASSWORD`** - Database password (automatically base64 encoded)
|
||||
|
||||
### Storage Configuration
|
||||
|
||||
- **`STORAGE_CLASS`** - Kubernetes StorageClass for persistent volumes
|
||||
- **`STORAGE_SIZE`** - Storage allocation for database
|
||||
|
||||
### Optional Configuration
|
||||
|
||||
- **`VITE_COUCHDB_URL`** - CouchDB URL for frontend
|
||||
- **`APP_BASE_URL`** - Application base URL
|
||||
|
||||
## 📁 Template Files
|
||||
|
||||
All Kubernetes manifests are now template-based:
|
||||
|
||||
1. **`k8s/couchdb-secret.yaml.template`** - Database credentials (uses `stringData`)
|
||||
2. **`k8s/couchdb-pvc.yaml.template`** - Persistent volume claim with configurable storage
|
||||
3. **`k8s/couchdb-service.yaml.template`** - Database service with dynamic naming
|
||||
4. **`k8s/couchdb-statefulset.yaml.template`** - Database deployment with storage config
|
||||
5. **`k8s/configmap.yaml.template`** - Application configuration
|
||||
6. **`k8s/frontend-deployment.yaml.template`** - Frontend with configurable image
|
||||
7. **`k8s/frontend-service.yaml.template`** - Frontend service with dynamic naming
|
||||
8. **`k8s/ingress.yaml.template`** - Ingress with configurable hostname
|
||||
|
||||
## 🎭 Environment Examples
|
||||
|
||||
### Development Environment
|
||||
|
||||
```bash
|
||||
# .env
|
||||
APP_NAME=rxminder-dev
|
||||
DOCKER_IMAGE=localhost:5000/rxminder:dev
|
||||
COUCHDB_USER=admin
|
||||
COUCHDB_PASSWORD=dev-password-123
|
||||
INGRESS_HOST=rxminder-dev.local
|
||||
STORAGE_CLASS=local-path
|
||||
STORAGE_SIZE=5Gi
|
||||
```
|
||||
|
||||
### Staging Environment
|
||||
|
||||
```bash
|
||||
# .env.staging
|
||||
APP_NAME=rxminder-staging
|
||||
DOCKER_IMAGE=registry.company.com/rxminder:staging
|
||||
COUCHDB_USER=admin
|
||||
COUCHDB_PASSWORD=staging-secure-password
|
||||
INGRESS_HOST=staging.rxminder.company.com
|
||||
STORAGE_CLASS=longhorn
|
||||
STORAGE_SIZE=10Gi
|
||||
```
|
||||
|
||||
### Production Environment
|
||||
|
||||
```bash
|
||||
# .env.production
|
||||
APP_NAME=rxminder
|
||||
DOCKER_IMAGE=registry.company.com/rxminder:v1.2.0
|
||||
COUCHDB_USER=admin
|
||||
COUCHDB_PASSWORD=ultra-secure-production-password
|
||||
INGRESS_HOST=rxminder.company.com
|
||||
STORAGE_CLASS=fast-ssd
|
||||
STORAGE_SIZE=50Gi
|
||||
```
|
||||
|
||||
### Cloud Provider Examples
|
||||
|
||||
#### AWS EKS
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
DOCKER_IMAGE=123456789012.dkr.ecr.us-west-2.amazonaws.com/rxminder:v1.0.0
|
||||
STORAGE_CLASS=gp3
|
||||
STORAGE_SIZE=20Gi
|
||||
INGRESS_HOST=rxminder.aws.company.com
|
||||
```
|
||||
|
||||
#### Google GKE
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
DOCKER_IMAGE=gcr.io/project-id/rxminder:stable
|
||||
STORAGE_CLASS=pd-ssd
|
||||
STORAGE_SIZE=20Gi
|
||||
INGRESS_HOST=rxminder.gcp.company.com
|
||||
```
|
||||
|
||||
#### Azure AKS
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
DOCKER_IMAGE=myregistry.azurecr.io/rxminder:production
|
||||
STORAGE_CLASS=managed-premium
|
||||
STORAGE_SIZE=20Gi
|
||||
INGRESS_HOST=rxminder.azure.company.com
|
||||
```
|
||||
|
||||
## 🚀 Deployment Workflow
|
||||
|
||||
### Simple 3-Step Process
|
||||
|
||||
```bash
|
||||
# 1. Configure environment
|
||||
cp .env.example .env
|
||||
nano .env # Edit with your values
|
||||
|
||||
# 2. Deploy with single command
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# 3. Check status
|
||||
./scripts/k8s-deploy-template.sh status
|
||||
```
|
||||
|
||||
### Advanced Deployment Options
|
||||
|
||||
```bash
|
||||
# Deploy with specific environment file
|
||||
ENV_FILE=.env.production ./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# Override specific variables
|
||||
export DOCKER_IMAGE=my-registry.com/rxminder:hotfix
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# Cleanup deployment
|
||||
./scripts/k8s-deploy-template.sh delete
|
||||
```
|
||||
|
||||
## 🎯 Generated Resources
|
||||
|
||||
### Before (Hardcoded)
|
||||
|
||||
```yaml
|
||||
# Old approach - static values
|
||||
metadata:
|
||||
name: frontend
|
||||
labels:
|
||||
app: rxminder
|
||||
spec:
|
||||
containers:
|
||||
- image: gitea-http.taildb3494.ts.net/will/meds:latest
|
||||
volumeClaimTemplates:
|
||||
- spec:
|
||||
storageClassName: longhorn
|
||||
resources:
|
||||
requests:
|
||||
storage: 1Gi
|
||||
```
|
||||
|
||||
### After (Template-Based)
|
||||
|
||||
```yaml
|
||||
# Template approach - dynamic values
|
||||
metadata:
|
||||
name: ${APP_NAME}-frontend
|
||||
labels:
|
||||
app: ${APP_NAME}
|
||||
spec:
|
||||
containers:
|
||||
- image: ${DOCKER_IMAGE}
|
||||
volumeClaimTemplates:
|
||||
- spec:
|
||||
storageClassName: ${STORAGE_CLASS}
|
||||
resources:
|
||||
requests:
|
||||
storage: ${STORAGE_SIZE}
|
||||
```
|
||||
|
||||
### Deployed Result
|
||||
|
||||
```yaml
|
||||
# After envsubst processing
|
||||
metadata:
|
||||
name: rxminder-frontend
|
||||
labels:
|
||||
app: rxminder
|
||||
spec:
|
||||
containers:
|
||||
- image: registry.company.com/rxminder:v1.0.0
|
||||
volumeClaimTemplates:
|
||||
- spec:
|
||||
storageClassName: fast-ssd
|
||||
resources:
|
||||
requests:
|
||||
storage: 20Gi
|
||||
```
|
||||
|
||||
## 🔄 CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Deploy to Kubernetes
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Deploy to Production
|
||||
env:
|
||||
APP_NAME: rxminder
|
||||
DOCKER_IMAGE: ghcr.io/${{ github.repository }}:${{ github.sha }}
|
||||
COUCHDB_PASSWORD: ${{ secrets.COUCHDB_PASSWORD }}
|
||||
INGRESS_HOST: rxminder.company.com
|
||||
STORAGE_CLASS: fast-ssd
|
||||
STORAGE_SIZE: 50Gi
|
||||
run: |
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
deploy_production:
|
||||
stage: deploy
|
||||
variables:
|
||||
APP_NAME: rxminder
|
||||
DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
|
||||
STORAGE_CLASS: longhorn
|
||||
STORAGE_SIZE: 20Gi
|
||||
script:
|
||||
- ./scripts/k8s-deploy-template.sh deploy
|
||||
only:
|
||||
- tags
|
||||
```
|
||||
|
||||
## 💡 Benefits Achieved
|
||||
|
||||
### 🎯 Flexibility
|
||||
|
||||
- ✅ **Multi-environment** deployments with same codebase
|
||||
- ✅ **Cloud-agnostic** configuration
|
||||
- ✅ **Registry-agnostic** image deployment
|
||||
- ✅ **Storage-flexible** for any Kubernetes cluster
|
||||
|
||||
### 🔒 Security
|
||||
|
||||
- ✅ **No hardcoded credentials** in version control
|
||||
- ✅ **Environment-specific secrets** management
|
||||
- ✅ **Automatic base64 encoding** via Kubernetes `stringData`
|
||||
- ✅ **Credential validation** before deployment
|
||||
|
||||
### 🛠️ Developer Experience
|
||||
|
||||
- ✅ **Single command deployment** across all environments
|
||||
- ✅ **Clear documentation** of all configuration options
|
||||
- ✅ **Environment validation** with helpful error messages
|
||||
- ✅ **Template debugging** with manual `envsubst` testing
|
||||
|
||||
### 🏢 Enterprise Ready
|
||||
|
||||
- ✅ **Production-grade** configuration management
|
||||
- ✅ **CI/CD integration** ready
|
||||
- ✅ **Multi-cluster** deployment support
|
||||
- ✅ **Disaster recovery** friendly with consistent configs
|
||||
|
||||
## 🎪 Use Cases
|
||||
|
||||
### Multi-Tenant Deployment
|
||||
|
||||
```bash
|
||||
# Tenant A
|
||||
export APP_NAME=rxminder-tenant-a
|
||||
export INGRESS_HOST=tenant-a.rxminder.company.com
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# Tenant B
|
||||
export APP_NAME=rxminder-tenant-b
|
||||
export INGRESS_HOST=tenant-b.rxminder.company.com
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
### Blue-Green Deployment
|
||||
|
||||
```bash
|
||||
# Blue environment
|
||||
export APP_NAME=rxminder-blue
|
||||
export DOCKER_IMAGE=registry.com/rxminder:v1.0.0
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# Green environment
|
||||
export APP_NAME=rxminder-green
|
||||
export DOCKER_IMAGE=registry.com/rxminder:v2.0.0
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
### Development Branches
|
||||
|
||||
```bash
|
||||
# Feature branch deployment
|
||||
export APP_NAME=rxminder-feature-auth
|
||||
export DOCKER_IMAGE=registry.com/rxminder:feature-auth
|
||||
export INGRESS_HOST=auth-feature.rxminder.dev.company.com
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
This **complete template-based approach** makes RxMinder the most **flexible**, **secure**, and **maintainable** medication reminder application for Kubernetes deployments!
|
||||
Reference in New Issue
Block a user