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
|
||||
Reference in New Issue
Block a user