rxminder/docs/deployment/DEPLOYMENT.md

# 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