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
538
docs/deployment/DEPLOYMENT.md
Normal file
538
docs/deployment/DEPLOYMENT.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# Deployment Guide
|
||||
|
||||
## 🚀 Complete Deployment Guide for Medication Reminder App
|
||||
|
||||
### **Prerequisites**
|
||||
|
||||
#### **System Requirements**
|
||||
|
||||
- Docker 20.10+ and Docker Compose 2.0+
|
||||
- 2GB RAM minimum, 4GB recommended
|
||||
- 10GB disk space for application and data
|
||||
- Linux/macOS/Windows with WSL2
|
||||
|
||||
#### **Required Accounts**
|
||||
|
||||
- [Mailgun Account](https://mailgun.com) for email services
|
||||
- Domain name for production deployment (optional)
|
||||
- SSL certificate for HTTPS (recommended)
|
||||
|
||||
### **Environment Setup**
|
||||
|
||||
#### **1. Clone Repository**
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd meds
|
||||
```
|
||||
|
||||
#### **2. Configure Environment**
|
||||
|
||||
```bash
|
||||
# Copy template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit with your credentials
|
||||
nano .env
|
||||
```
|
||||
|
||||
**Required Variables:**
|
||||
|
||||
```bash
|
||||
# Application Configuration
|
||||
APP_BASE_URL=https://yourdomain.com
|
||||
|
||||
# CouchDB Configuration
|
||||
COUCHDB_USER=admin
|
||||
COUCHDB_PASSWORD=super-secure-password-123!
|
||||
VITE_COUCHDB_URL=http://couchdb:5984
|
||||
VITE_COUCHDB_USER=admin
|
||||
VITE_COUCHDB_PASSWORD=super-secure-password-123!
|
||||
|
||||
# Mailgun Configuration
|
||||
MAILGUN_API_KEY=key-1234567890abcdef1234567890abcdef
|
||||
MAILGUN_DOMAIN=mg.yourdomain.com
|
||||
MAILGUN_FROM_EMAIL=noreply@yourdomain.com
|
||||
|
||||
# Production Settings
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
### **Local Development Deployment**
|
||||
|
||||
#### **Quick Start**
|
||||
|
||||
```bash
|
||||
# Automated setup
|
||||
./setup.sh
|
||||
|
||||
# Manual setup
|
||||
bun install
|
||||
docker compose up -d
|
||||
bun run seed-production.js
|
||||
```
|
||||
|
||||
#### **Development URLs**
|
||||
|
||||
- Frontend: http://localhost:8080
|
||||
- CouchDB: http://localhost:5984
|
||||
- Admin Panel: http://localhost:5984/\_utils
|
||||
|
||||
### **Production Deployment**
|
||||
|
||||
#### **Method 1: Automated Script**
|
||||
|
||||
```bash
|
||||
# Secure deployment with validation
|
||||
./deploy.sh production
|
||||
```
|
||||
|
||||
#### **Method 2: Manual Docker Compose**
|
||||
|
||||
```bash
|
||||
# Build images
|
||||
docker compose build --no-cache
|
||||
|
||||
# Start services
|
||||
docker compose up -d
|
||||
|
||||
# Seed database
|
||||
node seed-production.js
|
||||
|
||||
# Verify deployment
|
||||
bun test-production.js
|
||||
```
|
||||
|
||||
#### **Method 3: Docker Swarm**
|
||||
|
||||
```bash
|
||||
# Initialize swarm
|
||||
docker swarm init
|
||||
|
||||
# Deploy stack
|
||||
docker stack deploy -c docker/docker-compose.yaml meds-stack
|
||||
|
||||
# Scale services
|
||||
docker service scale meds-stack_frontend=3
|
||||
```
|
||||
|
||||
### **Cloud Platform Deployments**
|
||||
|
||||
#### **AWS EC2 Deployment**
|
||||
|
||||
**1. Launch EC2 Instance**
|
||||
|
||||
```bash
|
||||
# Amazon Linux 2 AMI
|
||||
# Instance type: t3.medium or larger
|
||||
# Security group: Allow ports 22, 80, 443, 8080
|
||||
```
|
||||
|
||||
**2. Install Dependencies**
|
||||
|
||||
```bash
|
||||
# Connect to instance
|
||||
ssh -i your-key.pem ec2-user@your-instance-ip
|
||||
|
||||
# Install Docker
|
||||
sudo yum update -y
|
||||
sudo yum install -y docker
|
||||
sudo service docker start
|
||||
sudo usermod -a -G docker ec2-user
|
||||
|
||||
# Install Docker Compose
|
||||
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
|
||||
sudo chmod +x /usr/local/bin/docker-compose
|
||||
```
|
||||
|
||||
**3. Deploy Application**
|
||||
|
||||
```bash
|
||||
# Clone and configure
|
||||
git clone <repository-url>
|
||||
cd meds
|
||||
cp .env.example .env
|
||||
# Edit .env with production values
|
||||
|
||||
# Deploy
|
||||
./deploy.sh production
|
||||
```
|
||||
|
||||
#### **Google Cloud Platform Deployment**
|
||||
|
||||
**1. Cloud Run Deployment**
|
||||
|
||||
```bash
|
||||
# Build and push image
|
||||
gcloud builds submit --tag gcr.io/PROJECT-ID/meds-app
|
||||
|
||||
# Deploy service
|
||||
gcloud run deploy meds-app \
|
||||
--image gcr.io/PROJECT-ID/meds-app \
|
||||
--platform managed \
|
||||
--region us-central1 \
|
||||
--set-env-vars COUCHDB_URL=your-couchdb-url \
|
||||
--set-env-vars MAILGUN_API_KEY=your-key \
|
||||
--allow-unauthenticated
|
||||
```
|
||||
|
||||
**2. Compute Engine Deployment**
|
||||
|
||||
```bash
|
||||
# Create instance
|
||||
gcloud compute instances create meds-server \
|
||||
--image-family debian-11 \
|
||||
--image-project debian-cloud \
|
||||
--machine-type e2-medium \
|
||||
--tags http-server,https-server
|
||||
|
||||
# SSH and install
|
||||
gcloud compute ssh meds-server
|
||||
# Follow standard installation steps
|
||||
```
|
||||
|
||||
#### **Digital Ocean Deployment**
|
||||
|
||||
**1. Droplet Setup**
|
||||
|
||||
```bash
|
||||
# Create droplet with Docker pre-installed
|
||||
# Or install Docker manually on Ubuntu droplet
|
||||
|
||||
# Connect and deploy
|
||||
ssh root@your-droplet-ip
|
||||
git clone <repository-url>
|
||||
cd meds
|
||||
./setup.sh
|
||||
./deploy.sh production
|
||||
```
|
||||
|
||||
**2. App Platform Deployment**
|
||||
|
||||
```bash
|
||||
# Create app.yaml
|
||||
version: 1
|
||||
services:
|
||||
- name: meds-app
|
||||
source_dir: /
|
||||
github:
|
||||
repo: your-username/meds
|
||||
branch: main
|
||||
build_command: bun run build
|
||||
environment_slug: node-js
|
||||
instance_count: 1
|
||||
instance_size_slug: basic-xxs
|
||||
envs:
|
||||
- key: COUCHDB_URL
|
||||
value: ${COUCHDB_URL}
|
||||
- key: MAILGUN_API_KEY
|
||||
value: ${MAILGUN_API_KEY}
|
||||
|
||||
# Deploy
|
||||
doctl apps create --spec app.yaml
|
||||
```
|
||||
|
||||
### **Kubernetes Deployment**
|
||||
|
||||
#### **Method 1: Automated Deployment Script (Recommended)**
|
||||
|
||||
```bash
|
||||
# Configure environment
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings:
|
||||
# INGRESS_HOST=app.meds.192.168.1.100.nip.io # For local cluster
|
||||
# INGRESS_HOST=meds.yourdomain.com # For production
|
||||
|
||||
# Deploy with environment substitution
|
||||
./deploy-k8s.sh
|
||||
|
||||
# Check deployment status
|
||||
./deploy-k8s.sh --status
|
||||
|
||||
# Deploy with custom environment file
|
||||
./deploy-k8s.sh --env .env.production
|
||||
|
||||
# Preview deployment (dry run)
|
||||
./deploy-k8s.sh --dry-run
|
||||
```
|
||||
|
||||
#### **Method 2: Manual Deployment**
|
||||
|
||||
#### **1. Create Namespace and Secrets**
|
||||
|
||||
```bash
|
||||
# Create namespace
|
||||
kubectl create namespace meds-app
|
||||
|
||||
# Create secrets
|
||||
kubectl create secret generic meds-secrets \
|
||||
--from-literal=couchdb-user=admin \
|
||||
--from-literal=couchdb-password=secure-password \
|
||||
--from-literal=mailgun-api-key=your-api-key \
|
||||
--namespace meds-app
|
||||
```
|
||||
|
||||
#### **2. Deploy Services**
|
||||
|
||||
```bash
|
||||
# Apply Kubernetes manifests
|
||||
kubectl apply -f k8s/ --namespace meds-app
|
||||
|
||||
# Check deployment status
|
||||
kubectl get pods -n meds-app
|
||||
kubectl get services -n meds-app
|
||||
```
|
||||
|
||||
#### **3. Configure Ingress (Manual)**
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: meds-ingress
|
||||
namespace: meds-app
|
||||
annotations:
|
||||
kubernetes.io/ingress.class: nginx
|
||||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- meds.yourdomain.com
|
||||
secretName: meds-tls
|
||||
rules:
|
||||
- host: meds.yourdomain.com # Update this to your domain
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: meds-frontend
|
||||
port:
|
||||
number: 80
|
||||
```
|
||||
|
||||
### **SSL/HTTPS Configuration**
|
||||
|
||||
#### **Let's Encrypt with Nginx**
|
||||
|
||||
```bash
|
||||
# Install certbot
|
||||
sudo apt-get install certbot python3-certbot-nginx
|
||||
|
||||
# Get certificate
|
||||
sudo certbot --nginx -d yourdomain.com
|
||||
|
||||
# Auto-renewal
|
||||
sudo crontab -e
|
||||
# Add: 0 12 * * * /usr/bin/certbot renew --quiet
|
||||
```
|
||||
|
||||
#### **Cloudflare SSL**
|
||||
|
||||
```bash
|
||||
# Update docker/nginx.conf for Cloudflare
|
||||
# Set ssl_certificate and ssl_certificate_key
|
||||
# Configure Cloudflare for Full (Strict) SSL
|
||||
```
|
||||
|
||||
### **Database Backup and Recovery**
|
||||
|
||||
#### **CouchDB Backup**
|
||||
|
||||
```bash
|
||||
# Create backup script
|
||||
#!/bin/bash
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
BACKUP_DIR="/backup/couchdb"
|
||||
|
||||
# Backup all databases
|
||||
curl -X GET http://admin:password@localhost:5984/_all_dbs | \
|
||||
jq -r '.[]' | while read db; do
|
||||
curl -X GET "http://admin:password@localhost:5984/$db/_all_docs?include_docs=true" \
|
||||
> "$BACKUP_DIR/${db}_${DATE}.json"
|
||||
done
|
||||
```
|
||||
|
||||
#### **Automated Backups**
|
||||
|
||||
```bash
|
||||
# Add to crontab
|
||||
0 2 * * * /opt/meds/backup-couchdb.sh
|
||||
|
||||
# Upload to cloud storage
|
||||
aws s3 cp /backup/couchdb/ s3://your-backup-bucket/ --recursive
|
||||
```
|
||||
|
||||
### **Monitoring and Logging**
|
||||
|
||||
#### **Health Checks**
|
||||
|
||||
```bash
|
||||
# Application health
|
||||
curl -f http://localhost:8080/health
|
||||
|
||||
# CouchDB health
|
||||
curl -f http://admin:password@localhost:5984/_up
|
||||
|
||||
# Docker container health
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
#### **Log Management**
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
docker compose logs -f frontend
|
||||
docker compose logs -f couchdb
|
||||
|
||||
# Log rotation
|
||||
# Configure in docker/docker-compose.yaml:
|
||||
logging:
|
||||
driver: "json-file"
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
```
|
||||
|
||||
#### **Performance Monitoring**
|
||||
|
||||
```bash
|
||||
# Resource usage
|
||||
docker stats
|
||||
|
||||
# Application metrics
|
||||
# Implement custom metrics endpoint
|
||||
# Use Prometheus/Grafana for monitoring
|
||||
```
|
||||
|
||||
### **Scaling and Load Balancing**
|
||||
|
||||
#### **Horizontal Scaling**
|
||||
|
||||
```bash
|
||||
# Scale frontend containers
|
||||
docker compose up -d --scale frontend=3
|
||||
|
||||
# Load balancer configuration
|
||||
# Use nginx, HAProxy, or cloud load balancer
|
||||
```
|
||||
|
||||
#### **Database Scaling**
|
||||
|
||||
```bash
|
||||
# CouchDB clustering
|
||||
# Configure multiple CouchDB nodes
|
||||
# Set up replication between nodes
|
||||
```
|
||||
|
||||
### **Security Hardening**
|
||||
|
||||
#### **Firewall Configuration**
|
||||
|
||||
```bash
|
||||
# UFW (Ubuntu)
|
||||
sudo ufw allow 22/tcp
|
||||
sudo ufw allow 80/tcp
|
||||
sudo ufw allow 443/tcp
|
||||
sudo ufw deny 5984/tcp # CouchDB admin (internal only)
|
||||
sudo ufw enable
|
||||
```
|
||||
|
||||
#### **Container Security**
|
||||
|
||||
```bash
|
||||
# Run security scan
|
||||
docker scout cves meds-frontend:latest
|
||||
|
||||
# Update base images regularly
|
||||
docker compose build --no-cache
|
||||
```
|
||||
|
||||
### **Troubleshooting**
|
||||
|
||||
#### **Common Issues**
|
||||
|
||||
**1. Environment Variables Not Loading**
|
||||
|
||||
```bash
|
||||
# Check file format
|
||||
cat -A .env
|
||||
|
||||
# Verify Docker Compose config
|
||||
docker compose config
|
||||
```
|
||||
|
||||
**2. Database Connection Issues**
|
||||
|
||||
```bash
|
||||
# Test CouchDB connection
|
||||
curl -u admin:password http://localhost:5984/
|
||||
|
||||
# Check container logs
|
||||
docker compose logs couchdb
|
||||
```
|
||||
|
||||
**3. Email Not Sending**
|
||||
|
||||
```bash
|
||||
# Verify Mailgun configuration
|
||||
curl -s --user 'api:YOUR_API_KEY' \
|
||||
https://api.mailgun.net/v3/YOUR_DOMAIN/messages \
|
||||
-F from='test@YOUR_DOMAIN' \
|
||||
-F to='you@example.com' \
|
||||
-F subject='Test' \
|
||||
-F text='Testing'
|
||||
```
|
||||
|
||||
**4. Frontend Build Failures**
|
||||
|
||||
```bash
|
||||
# Clear cache and rebuild
|
||||
docker compose build --no-cache frontend
|
||||
```
|
||||
|
||||
### **Maintenance**
|
||||
|
||||
#### **Regular Tasks**
|
||||
|
||||
- Update dependencies monthly
|
||||
- Rotate credentials quarterly
|
||||
- Backup database daily
|
||||
- Monitor disk space weekly
|
||||
- Review security logs daily
|
||||
|
||||
#### **Update Process**
|
||||
|
||||
```bash
|
||||
# 1. Backup current deployment
|
||||
./backup.sh
|
||||
|
||||
# 2. Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# 3. Update dependencies
|
||||
bun install
|
||||
|
||||
# 4. Rebuild and deploy
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
|
||||
# 5. Verify deployment
|
||||
bun test-production.js
|
||||
```
|
||||
|
||||
### **Support and Documentation**
|
||||
|
||||
#### **Getting Help**
|
||||
|
||||
- GitHub Issues: Create issue for bugs/features
|
||||
- Documentation: Check README.md and docs/
|
||||
- Community: Join our Discord/Slack channel
|
||||
|
||||
#### **Professional Support**
|
||||
|
||||
- Enterprise support available
|
||||
- Custom deployment assistance
|
||||
- Security auditing services
|
||||
- Performance optimization consulting
|
||||
265
docs/deployment/DOCKER_IMAGE_CONFIGURATION.md
Normal file
265
docs/deployment/DOCKER_IMAGE_CONFIGURATION.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 🐳 Docker Image Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
RxMinder now supports configurable Docker images via environment variables, enabling flexible deployment across different registries, environments, and versions.
|
||||
|
||||
## 🎯 Docker Image Variable
|
||||
|
||||
### **DOCKER_IMAGE**
|
||||
|
||||
The complete Docker image specification including registry, repository, and tag.
|
||||
|
||||
**Format:** `[registry/]repository:tag`
|
||||
|
||||
## 🌐 Registry Examples
|
||||
|
||||
### Public Registries
|
||||
|
||||
#### Docker Hub
|
||||
|
||||
```bash
|
||||
# Official image on Docker Hub
|
||||
DOCKER_IMAGE=rxminder/rxminder:latest
|
||||
DOCKER_IMAGE=rxminder/rxminder:v1.2.0
|
||||
DOCKER_IMAGE=rxminder/rxminder:stable
|
||||
```
|
||||
|
||||
#### GitHub Container Registry (ghcr.io)
|
||||
|
||||
```bash
|
||||
# GitHub Packages
|
||||
DOCKER_IMAGE=ghcr.io/username/rxminder:latest
|
||||
DOCKER_IMAGE=ghcr.io/organization/rxminder:v1.2.0
|
||||
DOCKER_IMAGE=ghcr.io/username/rxminder:dev-branch
|
||||
```
|
||||
|
||||
#### GitLab Container Registry
|
||||
|
||||
```bash
|
||||
# GitLab Registry
|
||||
DOCKER_IMAGE=registry.gitlab.com/username/rxminder:latest
|
||||
DOCKER_IMAGE=registry.gitlab.com/group/rxminder:production
|
||||
```
|
||||
|
||||
### Private/Self-Hosted Registries
|
||||
|
||||
#### Gitea Registry
|
||||
|
||||
```bash
|
||||
# Current default (Gitea)
|
||||
DOCKER_IMAGE=gitea-http.taildb3494.ts.net/will/meds:latest
|
||||
DOCKER_IMAGE=gitea-http.taildb3494.ts.net/will/meds:v1.2.0
|
||||
```
|
||||
|
||||
#### Harbor Registry
|
||||
|
||||
```bash
|
||||
# Harbor enterprise registry
|
||||
DOCKER_IMAGE=harbor.company.com/rxminder/rxminder:latest
|
||||
DOCKER_IMAGE=harbor.company.com/rxminder/rxminder:production
|
||||
```
|
||||
|
||||
#### Local Registry
|
||||
|
||||
```bash
|
||||
# Local development registry
|
||||
DOCKER_IMAGE=localhost:5000/rxminder:latest
|
||||
DOCKER_IMAGE=registry.local:5000/rxminder:dev
|
||||
```
|
||||
|
||||
### Cloud Provider Registries
|
||||
|
||||
#### AWS Elastic Container Registry (ECR)
|
||||
|
||||
```bash
|
||||
# AWS ECR
|
||||
DOCKER_IMAGE=123456789012.dkr.ecr.us-west-2.amazonaws.com/rxminder:latest
|
||||
DOCKER_IMAGE=123456789012.dkr.ecr.us-west-2.amazonaws.com/rxminder:v1.2.0
|
||||
```
|
||||
|
||||
#### Google Container Registry (GCR)
|
||||
|
||||
```bash
|
||||
# Google Cloud Registry
|
||||
DOCKER_IMAGE=gcr.io/project-id/rxminder:latest
|
||||
DOCKER_IMAGE=us.gcr.io/project-id/rxminder:production
|
||||
```
|
||||
|
||||
#### Azure Container Registry (ACR)
|
||||
|
||||
```bash
|
||||
# Azure Container Registry
|
||||
DOCKER_IMAGE=myregistry.azurecr.io/rxminder:latest
|
||||
DOCKER_IMAGE=myregistry.azurecr.io/rxminder:stable
|
||||
```
|
||||
|
||||
## 🏷️ Tagging Strategies
|
||||
|
||||
### Environment-Based Tagging
|
||||
|
||||
```bash
|
||||
# Development
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:dev
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:develop-20250906
|
||||
|
||||
# Staging
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:staging
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:release-candidate
|
||||
|
||||
# Production
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:stable
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:v1.2.0
|
||||
```
|
||||
|
||||
### Git-Based Tagging
|
||||
|
||||
```bash
|
||||
# Branch-based
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:main
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:feature-auth
|
||||
|
||||
# Commit-based
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:sha-abc1234
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:pr-123
|
||||
```
|
||||
|
||||
### Semantic Versioning
|
||||
|
||||
```bash
|
||||
# Semantic versions
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:v1.0.0
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:v1.2.3-beta
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:v2.0.0-rc1
|
||||
```
|
||||
|
||||
## 🎪 Environment-Specific Configurations
|
||||
|
||||
### Development (.env)
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder-dev
|
||||
DOCKER_IMAGE=localhost:5000/rxminder:dev
|
||||
STORAGE_CLASS=local-path
|
||||
STORAGE_SIZE=5Gi
|
||||
INGRESS_HOST=rxminder-dev.local
|
||||
```
|
||||
|
||||
### Staging (.env.staging)
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder-staging
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:staging
|
||||
STORAGE_CLASS=longhorn
|
||||
STORAGE_SIZE=10Gi
|
||||
INGRESS_HOST=staging.rxminder.company.com
|
||||
```
|
||||
|
||||
### Production (.env.production)
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
DOCKER_IMAGE=myregistry.com/rxminder:v1.2.0 # Fixed version for stability
|
||||
STORAGE_CLASS=fast-ssd
|
||||
STORAGE_SIZE=50Gi
|
||||
INGRESS_HOST=rxminder.company.com
|
||||
```
|
||||
|
||||
## 🚀 CI/CD Integration
|
||||
|
||||
### GitHub Actions Example
|
||||
|
||||
```yaml
|
||||
# .github/workflows/deploy.yml
|
||||
- name: Deploy to Kubernetes
|
||||
env:
|
||||
DOCKER_IMAGE: ghcr.io/${{ github.repository }}:${{ github.sha }}
|
||||
run: |
|
||||
echo "DOCKER_IMAGE=${DOCKER_IMAGE}" >> .env
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
### GitLab CI Example
|
||||
|
||||
```yaml
|
||||
# .gitlab-ci.yml
|
||||
deploy:
|
||||
variables:
|
||||
DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
|
||||
script:
|
||||
- echo "DOCKER_IMAGE=${DOCKER_IMAGE}" >> .env
|
||||
- ./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
## 🔒 Registry Authentication
|
||||
|
||||
### Docker Registry Secrets
|
||||
|
||||
```bash
|
||||
# Create registry secret for private registries
|
||||
kubectl create secret docker-registry regcred \
|
||||
--docker-server=myregistry.com \
|
||||
--docker-username=username \
|
||||
--docker-password=password \
|
||||
--docker-email=email@company.com
|
||||
|
||||
# Update deployment to use the secret
|
||||
# (Add imagePullSecrets to deployment template if needed)
|
||||
```
|
||||
|
||||
### Cloud Provider Authentication
|
||||
|
||||
```bash
|
||||
# AWS ECR
|
||||
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com
|
||||
|
||||
# Google GCR
|
||||
gcloud auth configure-docker
|
||||
|
||||
# Azure ACR
|
||||
az acr login --name myregistry
|
||||
```
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Production Recommendations
|
||||
|
||||
- ✅ **Use specific tags** (not `:latest`) for production
|
||||
- ✅ **Pin to exact versions** for stability
|
||||
- ✅ **Use semantic versioning** for releases
|
||||
- ✅ **Separate registries** for different environments
|
||||
- ✅ **Enable vulnerability scanning** on registries
|
||||
|
||||
### Development Workflow
|
||||
|
||||
- ✅ **Use `:dev` or `:latest`** for development
|
||||
- ✅ **Branch-based tags** for feature development
|
||||
- ✅ **Local registries** for fast iteration
|
||||
- ✅ **Automated builds** on code changes
|
||||
|
||||
### Security Considerations
|
||||
|
||||
- ✅ **Private registries** for proprietary code
|
||||
- ✅ **Registry authentication** properly configured
|
||||
- ✅ **Image scanning** for vulnerabilities
|
||||
- ✅ **Supply chain security** with signed images
|
||||
|
||||
## 🎭 Example Deployments
|
||||
|
||||
### Multi-Environment Setup
|
||||
|
||||
```bash
|
||||
# Development
|
||||
export DOCKER_IMAGE=localhost:5000/rxminder:dev
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# Staging
|
||||
export DOCKER_IMAGE=registry.company.com/rxminder:staging
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
|
||||
# Production
|
||||
export DOCKER_IMAGE=registry.company.com/rxminder:v1.2.0
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
This flexible Docker image configuration makes RxMinder truly **portable** and **CI/CD-ready** across any container registry and deployment environment!
|
||||
242
docs/deployment/GITEA_SETUP.md
Normal file
242
docs/deployment/GITEA_SETUP.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# 🦌 Gitea CI/CD Setup Complete!
|
||||
|
||||
Your RxMinder app now has comprehensive Gitea Actions CI/CD support! Here's what's been created:
|
||||
|
||||
## 📁 New Files Structure
|
||||
|
||||
```
|
||||
.gitea/
|
||||
├── workflows/
|
||||
│ └── ci-cd.yml # Main CI/CD workflow
|
||||
├── docker-compose.ci.yml # CI-specific compose override
|
||||
├── gitea-bake.hcl # Gitea-optimized buildx config
|
||||
└── README.md # Detailed Gitea configuration guide
|
||||
|
||||
scripts/
|
||||
├── gitea-deploy.sh # Gitea-specific deployment script
|
||||
└── gitea-helper.sh # Comprehensive Gitea operations helper
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. **Setup Environment Configuration**
|
||||
|
||||
```bash
|
||||
# Copy the example environment file and customize
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env with your registry and configuration:
|
||||
CONTAINER_REGISTRY=gitea.yourdomain.com
|
||||
CONTAINER_REPOSITORY=username/rxminder
|
||||
GITEA_REGISTRY=gitea.yourdomain.com
|
||||
GITEA_REPOSITORY=username/rxminder
|
||||
```
|
||||
|
||||
### 2. **Setup Gitea Repository**
|
||||
|
||||
```bash
|
||||
# Configure in Gitea Repository Settings → Actions
|
||||
|
||||
# Required Secrets:
|
||||
GITEA_TOKEN # Personal access token with package write permissions
|
||||
VITE_COUCHDB_PASSWORD # CouchDB password
|
||||
DEPLOYMENT_WEBHOOK_URL # Optional: deployment notifications
|
||||
|
||||
# Repository Variables (optional - will use .env defaults):
|
||||
GITEA_REGISTRY # Override registry from .env
|
||||
VITE_COUCHDB_URL # http://localhost:5984
|
||||
VITE_COUCHDB_USER # admin
|
||||
APP_BASE_URL # http://localhost:8080
|
||||
```
|
||||
|
||||
### 3. **Local Development with Gitea**
|
||||
|
||||
```bash
|
||||
# Setup Gitea buildx builder
|
||||
bun run gitea:setup
|
||||
|
||||
# Build for local development
|
||||
bun run gitea:build-local
|
||||
|
||||
# Run tests
|
||||
bun run gitea:test
|
||||
|
||||
# Check status
|
||||
bun run gitea:status
|
||||
```
|
||||
|
||||
### 4. **Production Deployment**
|
||||
|
||||
```bash
|
||||
# Build and push to registry
|
||||
export GITEA_TOKEN=your_token
|
||||
export GITEA_REGISTRY=your-gitea.com
|
||||
export GITEA_REPOSITORY=username/rxminder
|
||||
|
||||
bun run gitea:build-prod v1.0.0
|
||||
|
||||
# Deploy to production
|
||||
bun run gitea:deploy production v1.0.0
|
||||
```
|
||||
|
||||
## 🔧 Gitea Actions Features
|
||||
|
||||
### **Multi-Platform Builds**
|
||||
|
||||
- ✅ AMD64 (Intel/AMD processors)
|
||||
- ✅ ARM64 (Apple Silicon, AWS Graviton)
|
||||
- ✅ Optimized layer caching
|
||||
- ✅ Registry-based build cache
|
||||
|
||||
### **Security & Quality**
|
||||
|
||||
- ✅ Trivy vulnerability scanning
|
||||
- ✅ Supply chain attestations (SBOM, provenance)
|
||||
- ✅ Dependency auditing
|
||||
- ✅ Lint and type checking
|
||||
|
||||
### **Deployment Options**
|
||||
|
||||
- ✅ Docker Compose deployment
|
||||
- ✅ Kubernetes deployment
|
||||
- ✅ Staging environment support
|
||||
- ✅ Health checks and monitoring
|
||||
|
||||
### **Automation**
|
||||
|
||||
- ✅ Automatic builds on push/PR
|
||||
- ✅ Multi-environment deployments
|
||||
- ✅ Image cleanup and maintenance
|
||||
- ✅ Deployment notifications
|
||||
|
||||
## 📋 Available Commands
|
||||
|
||||
### **Gitea Helper Script**
|
||||
|
||||
```bash
|
||||
./scripts/gitea-helper.sh setup # Setup buildx for Gitea
|
||||
./scripts/gitea-helper.sh build-local # Local development build
|
||||
./scripts/gitea-helper.sh build-multi # Multi-platform build
|
||||
./scripts/gitea-helper.sh build-staging # Staging build
|
||||
./scripts/gitea-helper.sh build-prod # Production build
|
||||
./scripts/gitea-helper.sh test # Run all tests
|
||||
./scripts/gitea-helper.sh deploy # Deploy to environment
|
||||
./scripts/gitea-helper.sh status # Show CI/CD status
|
||||
./scripts/gitea-helper.sh cleanup # Cleanup builders/images
|
||||
```
|
||||
|
||||
### **Package.json Scripts**
|
||||
|
||||
```bash
|
||||
bun run gitea:setup # Setup Gitea buildx
|
||||
bun run gitea:build # Multi-platform build
|
||||
bun run gitea:build-local # Local development
|
||||
bun run gitea:build-staging # Staging build
|
||||
bun run gitea:build-prod # Production build
|
||||
bun run gitea:test # Run tests
|
||||
bun run gitea:deploy # Deploy application
|
||||
bun run gitea:status # Check status
|
||||
bun run gitea:cleanup # Cleanup
|
||||
```
|
||||
|
||||
## 🎯 Workflow Triggers
|
||||
|
||||
### **Automatic Triggers**
|
||||
|
||||
- **Push to main/develop**: Full build, test, and deploy
|
||||
- **Pull Request**: Build, test, and security scan
|
||||
- **Manual dispatch**: On-demand deployment
|
||||
|
||||
### **Environment-Specific**
|
||||
|
||||
- **Development**: Fast single-platform builds
|
||||
- **Staging**: Full testing with staging configs
|
||||
- **Production**: Multi-platform with attestations
|
||||
|
||||
## 🔒 Security Features
|
||||
|
||||
### **Image Security**
|
||||
|
||||
- Vulnerability scanning with Trivy
|
||||
- Base image security updates
|
||||
- Minimal attack surface
|
||||
- Supply chain attestations
|
||||
|
||||
### **Secrets Management**
|
||||
|
||||
- Gitea-native secrets storage
|
||||
- Environment-specific variables
|
||||
- Token rotation support
|
||||
- Secure registry authentication
|
||||
|
||||
## 📊 Monitoring & Notifications
|
||||
|
||||
### **Health Checks**
|
||||
|
||||
- Frontend application health
|
||||
- Database connectivity
|
||||
- Service dependency checks
|
||||
- Container resource monitoring
|
||||
|
||||
### **Notifications**
|
||||
|
||||
- Deployment success/failure alerts
|
||||
- Security scan results
|
||||
- Build status updates
|
||||
- Custom webhook integration
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **Configure Gitea Repository**:
|
||||
- Enable Actions in repository settings
|
||||
- Add required secrets and variables
|
||||
- Configure container registry
|
||||
|
||||
2. **Set up Gitea Runner**:
|
||||
- Install and configure Gitea Actions runner
|
||||
- Ensure Docker and buildx support
|
||||
- Configure appropriate labels
|
||||
|
||||
3. **Test the Pipeline**:
|
||||
|
||||
```bash
|
||||
# Push to trigger the workflow
|
||||
git add .
|
||||
git commit -m "Setup Gitea CI/CD"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
4. **Customize for Your Environment**:
|
||||
- Update registry URLs in `.gitea/gitea-bake.hcl`
|
||||
- Modify deployment targets in `scripts/gitea-deploy.sh`
|
||||
- Configure environment-specific variables
|
||||
|
||||
## 🔄 Migration Notes
|
||||
|
||||
- ✅ **Fully compatible** with existing Docker Buildx setup
|
||||
- ✅ **No breaking changes** to development workflow
|
||||
- ✅ **Parallel support** with GitHub Actions if needed
|
||||
- ✅ **Easy rollback** - simply delete `.gitea/` directory
|
||||
|
||||
Your RxMinder app is now ready for professional-grade CI/CD with Gitea! 🎉
|
||||
|
||||
## 📞 Troubleshooting
|
||||
|
||||
### Common Issues:
|
||||
|
||||
1. **Build failures**: Check Gitea runner has Docker buildx
|
||||
2. **Registry push errors**: Verify GITEA_TOKEN permissions
|
||||
3. **Deployment issues**: Check environment variables and secrets
|
||||
|
||||
### Debug Commands:
|
||||
|
||||
```bash
|
||||
# Check Gitea environment
|
||||
./scripts/gitea-helper.sh status
|
||||
|
||||
# Test local build
|
||||
./scripts/gitea-helper.sh build-local
|
||||
|
||||
# Verify registry login
|
||||
docker login your-gitea.com
|
||||
```
|
||||
226
docs/deployment/STORAGE_CONFIGURATION.md
Normal file
226
docs/deployment/STORAGE_CONFIGURATION.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 📦 Storage Configuration Examples
|
||||
|
||||
## Overview
|
||||
|
||||
RxMinder now supports configurable storage through environment variables, making it easy to adapt to different Kubernetes environments and storage requirements.
|
||||
|
||||
## 🗂️ Storage Configuration Variables
|
||||
|
||||
### **STORAGE_CLASS**
|
||||
|
||||
The Kubernetes StorageClass to use for persistent volumes.
|
||||
|
||||
**Common Options:**
|
||||
|
||||
- `longhorn` - Longhorn distributed storage (Raspberry Pi clusters)
|
||||
- `local-path` - Local path provisioner (k3s default)
|
||||
- `standard` - Cloud provider standard storage
|
||||
- `fast-ssd` - High-performance SSD storage
|
||||
- `gp2` - AWS General Purpose SSD
|
||||
- `pd-standard` - Google Cloud Standard Persistent Disk
|
||||
- `azure-disk` - Azure Standard Disk
|
||||
|
||||
### **STORAGE_SIZE**
|
||||
|
||||
The amount of storage to allocate for the CouchDB database.
|
||||
|
||||
**Sizing Guidelines:**
|
||||
|
||||
- `1Gi` - Minimal testing (not recommended for production)
|
||||
- `5Gi` - Small deployment (default, good for development)
|
||||
- `10Gi` - Medium deployment (suitable for small teams)
|
||||
- `20Gi` - Large deployment (production use)
|
||||
- `50Gi+` - Enterprise deployment (high-volume usage)
|
||||
|
||||
## 🎯 Environment-Specific Examples
|
||||
|
||||
### Development (.env)
|
||||
|
||||
```bash
|
||||
# Development environment
|
||||
APP_NAME=rxminder-dev
|
||||
STORAGE_CLASS=local-path
|
||||
STORAGE_SIZE=5Gi
|
||||
INGRESS_HOST=rxminder-dev.local
|
||||
```
|
||||
|
||||
### Staging (.env.staging)
|
||||
|
||||
```bash
|
||||
# Staging environment
|
||||
APP_NAME=rxminder-staging
|
||||
STORAGE_CLASS=longhorn
|
||||
STORAGE_SIZE=10Gi
|
||||
INGRESS_HOST=staging.rxminder.company.com
|
||||
```
|
||||
|
||||
### Production (.env.production)
|
||||
|
||||
```bash
|
||||
# Production environment
|
||||
APP_NAME=rxminder
|
||||
STORAGE_CLASS=fast-ssd
|
||||
STORAGE_SIZE=50Gi
|
||||
INGRESS_HOST=rxminder.company.com
|
||||
```
|
||||
|
||||
### Cloud Providers
|
||||
|
||||
#### AWS EKS
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
STORAGE_CLASS=gp2 # General Purpose SSD
|
||||
STORAGE_SIZE=20Gi
|
||||
INGRESS_HOST=rxminder.aws.company.com
|
||||
```
|
||||
|
||||
#### Google GKE
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
STORAGE_CLASS=pd-standard # Standard Persistent Disk
|
||||
STORAGE_SIZE=20Gi
|
||||
INGRESS_HOST=rxminder.gcp.company.com
|
||||
```
|
||||
|
||||
#### Azure AKS
|
||||
|
||||
```bash
|
||||
APP_NAME=rxminder
|
||||
STORAGE_CLASS=managed-premium # Premium SSD
|
||||
STORAGE_SIZE=20Gi
|
||||
INGRESS_HOST=rxminder.azure.company.com
|
||||
```
|
||||
|
||||
## 🏗️ Generated Kubernetes Resources
|
||||
|
||||
### Before (Hardcoded)
|
||||
|
||||
```yaml
|
||||
# Old approach - hardcoded values
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: couchdb-pvc
|
||||
spec:
|
||||
storageClassName: longhorn
|
||||
resources:
|
||||
requests:
|
||||
storage: 1Gi
|
||||
```
|
||||
|
||||
### After (Template-Based)
|
||||
|
||||
```yaml
|
||||
# Template: k8s/couchdb-pvc.yaml.template
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: ${APP_NAME}-couchdb-pvc
|
||||
labels:
|
||||
app: ${APP_NAME}
|
||||
spec:
|
||||
storageClassName: ${STORAGE_CLASS}
|
||||
resources:
|
||||
requests:
|
||||
storage: ${STORAGE_SIZE}
|
||||
```
|
||||
|
||||
### Deployed Result
|
||||
|
||||
```yaml
|
||||
# After envsubst processing
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: rxminder-couchdb-pvc
|
||||
labels:
|
||||
app: rxminder
|
||||
spec:
|
||||
storageClassName: fast-ssd
|
||||
resources:
|
||||
requests:
|
||||
storage: 20Gi
|
||||
```
|
||||
|
||||
## 🚀 Deployment Examples
|
||||
|
||||
### Quick Development Setup
|
||||
|
||||
```bash
|
||||
# Development with local storage
|
||||
export APP_NAME=rxminder-dev
|
||||
export STORAGE_CLASS=local-path
|
||||
export STORAGE_SIZE=5Gi
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
```bash
|
||||
# Copy production environment
|
||||
cp .env.production .env
|
||||
# Edit with your specific values
|
||||
nano .env
|
||||
|
||||
# Deploy to production
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
```bash
|
||||
# Override specific values
|
||||
export STORAGE_CLASS=custom-storage
|
||||
export STORAGE_SIZE=100Gi
|
||||
./scripts/k8s-deploy-template.sh deploy
|
||||
```
|
||||
|
||||
## 🔍 Storage Class Discovery
|
||||
|
||||
### Find Available Storage Classes
|
||||
|
||||
```bash
|
||||
# List available storage classes in your cluster
|
||||
kubectl get storageclass
|
||||
|
||||
# Get details about a specific storage class
|
||||
kubectl describe storageclass longhorn
|
||||
```
|
||||
|
||||
### Common Storage Class Names by Platform
|
||||
|
||||
| Platform | Common Storage Classes |
|
||||
| -------------- | ------------------------------------------ |
|
||||
| **k3s** | `local-path` (default) |
|
||||
| **Longhorn** | `longhorn` |
|
||||
| **AWS EKS** | `gp2`, `gp3`, `io1`, `io2` |
|
||||
| **Google GKE** | `standard`, `ssd`, `pd-standard`, `pd-ssd` |
|
||||
| **Azure AKS** | `default`, `managed-premium` |
|
||||
| **Rancher** | `longhorn`, `local-path` |
|
||||
|
||||
## 💡 Benefits
|
||||
|
||||
### Flexibility
|
||||
|
||||
- ✅ **Environment-specific** storage configuration
|
||||
- ✅ **Cloud-agnostic** deployment
|
||||
- ✅ **Performance tuning** via storage class selection
|
||||
- ✅ **Cost optimization** through appropriate sizing
|
||||
|
||||
### Maintainability
|
||||
|
||||
- ✅ **Single source of truth** via `.env` files
|
||||
- ✅ **Easy scaling** by changing STORAGE_SIZE
|
||||
- ✅ **Environment promotion** using different .env files
|
||||
- ✅ **Disaster recovery** with consistent configurations
|
||||
|
||||
### Developer Experience
|
||||
|
||||
- ✅ **No hardcoded values** in manifests
|
||||
- ✅ **Clear documentation** of requirements
|
||||
- ✅ **Validation** of required variables
|
||||
- ✅ **Automated deployment** with proper storage setup
|
||||
|
||||
This approach makes RxMinder truly **portable** across different Kubernetes environments while maintaining **production-grade** storage management!
|
||||
Reference in New Issue
Block a user