rxminder/docs/QUICK_DEPLOYMENT.md

Quick Deployment Guide

This guide provides simple, practical deployment options for the RxMinder application, ranging from local development to production deployment.

🚀 Instant Local Deployment

For immediate testing and development, use the local Docker deployment:

# Deploy locally with Docker (includes database)
make deploy-local

# Access the application
open http://localhost:8080

# Stop when done
make stop-local

This deployment:

• ✅ Includes CouchDB database
• ✅ Uses development configuration (safe defaults)
• ✅ Accessible at http://localhost:8080
• ✅ No additional configuration required
• ✅ Perfect for testing and development

📋 Deployment Options Overview

Method	Use Case	Requirements	URL	Command
Development Server	Active development	Node.js/Bun	http://localhost:5173	make dev
Local Docker	Testing/Demo	Docker	http://localhost:8080	make deploy-local
Production (Auto)	Production with auto-secrets	Kubernetes cluster	Configured domain	make deploy-prod-quick
Production (Manual)	Production with custom secrets	Kubernetes + secrets	Configured domain	make deploy-prod-configured

🔧 Development Deployment

Option 1: Development Server (Fastest)

# Install dependencies
make install

# Start development server
make dev

• Hot reloading enabled
• Access at http://localhost:5173
• Uses mock database (in-memory)
• Best for active development

Option 2: Built Application Preview

# Build and preview
make build
make preview

• Simulates production build
• Access at http://localhost:4173
• Uses mock database
• Good for testing build process

🐳 Docker Deployment

Local Docker Deployment (Recommended for Testing)

# Deploy with Docker Compose
make deploy-local

What this includes:

• Frontend application (Nginx)
• CouchDB database with persistent data
• Health checks and monitoring
• Automatic restart policies

Access:

• Application: http://localhost:8080
• CouchDB Admin: http://localhost:5984/_utils

Management:

# View logs
docker-compose -f docker/docker-compose.yaml logs -f

# Stop deployment
make stop-local

# Restart deployment
make deploy-local

# Clean up completely
make docker-clean

Docker Compose Manual Commands

# Start services
docker-compose -f docker/docker-compose.yaml up -d

# Stop services
docker-compose -f docker/docker-compose.yaml down

# View logs
docker-compose -f docker/docker-compose.yaml logs -f frontend
docker-compose -f docker/docker-compose.yaml logs -f couchdb

# Rebuild and restart
docker-compose -f docker/docker-compose.yaml up -d --build

☸️ Kubernetes Deployment

Prerequisites

1. Kubernetes cluster with kubectl configured
2. Cluster admin access to create namespaces
3. Ingress controller (optional, for external access)

Create Required Namespaces

# Create development namespace
kubectl create namespace rxminder-dev

# Create production namespace
kubectl create namespace rxminder-prod

Development Deployment

# Deploy to development environment
make deploy-dev

# Check status
make status-dev

# View logs
kubectl logs -n rxminder-dev -l app=rxminder

# Remove deployment
make undeploy-dev

Production Deployment

Option A: Auto-Generated Secrets (Quick)

# Deploy with automatically generated secrets
make deploy-prod-quick

Option B: Custom Configuration (Recommended)

# Set your production secrets
export JWT_SECRET="your-secure-jwt-secret-here"
export SESSION_SECRET="your-secure-session-secret-here"
export VITE_COUCHDB_URL="https://your-couchdb-instance.com"

# Deploy with your configuration
make deploy-prod-configured

Option C: Using Configuration Files

# Generate production configuration
make generate-config-prod

# Edit the generated files
nano .env.production

# Deploy
make build-prod
make deploy-prod

Kubernetes Management

# Check deployment status
make status-prod
make status-dev

# View differences before applying
make diff-prod
make diff-dev

# Validate configurations
make validate-k8s

# Remove deployments
make undeploy-prod
make undeploy-dev
make undeploy-all

🔒 Production Configuration

Required Environment Variables

For production deployment, you must set:

# Authentication (Required)
JWT_SECRET="your-secure-32-character-secret"
SESSION_SECRET="your-secure-32-character-secret"

# Database (Required for persistence)
VITE_COUCHDB_URL="https://your-couchdb.com"
COUCHDB_USER="your-username"
COUCHDB_PASSWORD="your-password"

Optional Configuration

# Email notifications
MAILGUN_API_KEY="your-mailgun-key"
MAILGUN_DOMAIN="your-domain.com"

# OAuth authentication
GOOGLE_CLIENT_ID="your-google-client-id"
GITHUB_CLIENT_ID="your-github-client-id"

Generate Secure Secrets

# Generate secure secrets
JWT_SECRET=$(openssl rand -base64 32)
SESSION_SECRET=$(openssl rand -base64 32)

echo "JWT_SECRET=$JWT_SECRET"
echo "SESSION_SECRET=$SESSION_SECRET"

🔍 Troubleshooting

Common Issues

Docker Issues

# If deployment fails
make docker-clean
make deploy-local

# If ports are in use
docker-compose -f docker/docker-compose.yaml down
# Wait a moment, then retry
make deploy-local

Build Issues

# For production build failures
# Check that secrets are set
echo $JWT_SECRET
echo $SESSION_SECRET

# Try development build instead
make build

Kubernetes Issues

# If namespace doesn't exist
kubectl create namespace rxminder-dev
kubectl create namespace rxminder-prod

# If deployment fails
kubectl get pods -n rxminder-dev
kubectl logs -n rxminder-dev <pod-name>

Health Checks

Local Docker Deployment

# Check if services are running
docker-compose -f docker/docker-compose.yaml ps

# Test frontend
curl http://localhost:8080

# Test CouchDB
curl http://localhost:5984/_up

Kubernetes Deployment

# Check pod status
kubectl get pods -n rxminder-prod

# Check service status
kubectl get services -n rxminder-prod

# View logs
kubectl logs -n rxminder-prod -l app=rxminder

📊 Monitoring

Docker Deployment

# View real-time logs
docker-compose -f docker/docker-compose.yaml logs -f

# Monitor resource usage
docker stats

Kubernetes Deployment

# Monitor pods
kubectl top pods -n rxminder-prod

# View events
kubectl get events -n rxminder-prod --sort-by='.lastTimestamp'

# Port forward for local access
kubectl port-forward -n rxminder-prod service/rxminder 8080:80

🔄 Updates and Maintenance

Update Local Deployment

# Pull latest changes
git pull

# Rebuild and restart
make deploy-local

Update Production Deployment

# Pull latest changes
git pull

# Build and deploy
make deploy-prod-quick

# Or with custom configuration
make deploy-prod-configured

Backup Data

Docker CouchDB

# CouchDB data is stored in docker/couchdb-data/
# Backup this directory
tar -czf couchdb-backup-$(date +%Y%m%d).tar.gz docker/couchdb-data/

Kubernetes CouchDB

# Access CouchDB pod
kubectl exec -n rxminder-prod -it <couchdb-pod> -- bash

# Use CouchDB backup tools
# Or backup persistent volume

🚀 Quick Commands Reference

# Development
make dev                    # Start development server
make build                  # Build for development
make test                   # Run tests

# Local deployment
make deploy-local          # Deploy with Docker
make stop-local           # Stop Docker deployment

# Production deployment
make deploy-prod-quick     # Deploy with auto-generated secrets
make deploy-prod-configured # Deploy with custom secrets

# Management
make help                  # Show all available commands
make validate-k8s         # Validate Kubernetes configs
make docker-clean         # Clean up Docker resources

---

Need more detailed information?

• Production Build Guide - Detailed production configuration
• Docker Configuration - Docker setup details
• Database Service - Database configuration
• Main README - Complete project overview

---

Last Updated: January 2024
Status: Ready for deployment