Files

William Valentin e48adbcb00 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

2025-09-06 01:42:48 -07:00

10 KiB

Raw Blame History

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 for email services
Domain name for production deployment (optional)
SSL certificate for HTTPS (recommended)

Environment Setup

1. Clone Repository

git clone <repository-url>
cd meds

2. Configure Environment

# Copy template
cp .env.example .env

# Edit with your credentials
nano .env

Required Variables:

# 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

# 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

# Secure deployment with validation
./deploy.sh production

Method 2: Manual Docker Compose

# 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

# 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

# Amazon Linux 2 AMI
# Instance type: t3.medium or larger
# Security group: Allow ports 22, 80, 443, 8080

2. Install Dependencies

# 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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)

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

# 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

# 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

# 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

# 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

# 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

# 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

# Resource usage
docker stats

# Application metrics
# Implement custom metrics endpoint
# Use Prometheus/Grafana for monitoring

Scaling and Load Balancing

Horizontal Scaling

# Scale frontend containers
docker compose up -d --scale frontend=3

# Load balancer configuration
# Use nginx, HAProxy, or cloud load balancer

Database Scaling

# CouchDB clustering
# Configure multiple CouchDB nodes
# Set up replication between nodes

Security Hardening

Firewall Configuration

# 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

# 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

# Check file format
cat -A .env

# Verify Docker Compose config
docker compose config

2. Database Connection Issues

# Test CouchDB connection
curl -u admin:password http://localhost:5984/

# Check container logs
docker compose logs couchdb

3. Email Not Sending

# 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

# 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

# 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

10 KiB Raw Blame History