430ed7458b
🚀 New Deployment Commands: - deploy-local: Docker-based local deployment (http://localhost:8080) - deploy-demo: Demo deployment with development settings - deploy-prod-quick: Production deployment with auto-generated secrets - deploy-prod-configured: Production deployment with pre-configured secrets - stop-local: Stop local Docker deployment 🔧 Fixes: - Fixed deploy-prod-quick to properly generate secure secrets - Updated local deployments to use development environment - Fixed Docker Compose environment variable handling - Improved error handling and user feedback 📚 Documentation: - Added Quick Deployment Guide (docs/QUICK_DEPLOYMENT.md) - Updated README with practical deployment guidance - Clear explanation of deployment options and use cases - Troubleshooting section for common issues ✨ Features: - Auto-generated secure JWT and session secrets for production - Local Docker deployment with persistent CouchDB - Clear separation between development and production processes - Comprehensive deployment option matrix 🧪 Verification: - ✅ Local deployment: make deploy-local (working with Docker) - ✅ Production build: JWT_SECRET=x SESSION_SECRET=y make build-prod (working) - ✅ Development build: make build (working) - ✅ All existing functionality preserved 🎯 Ready for use: - Immediate testing: make deploy-local - Production deployment: make deploy-prod-quick
424 lines
8.6 KiB
Markdown
424 lines
8.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Create development namespace
|
|
kubectl create namespace rxminder-dev
|
|
|
|
# Create production namespace
|
|
kubectl create namespace rxminder-prod
|
|
```
|
|
|
|
### Development Deployment
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# Deploy with automatically generated secrets
|
|
make deploy-prod-quick
|
|
```
|
|
|
|
#### Option B: Custom Configuration (Recommended)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Generate production configuration
|
|
make generate-config-prod
|
|
|
|
# Edit the generated files
|
|
nano .env.production
|
|
|
|
# Deploy
|
|
make build-prod
|
|
make deploy-prod
|
|
```
|
|
|
|
### Kubernetes Management
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# For production build failures
|
|
# Check that secrets are set
|
|
echo $JWT_SECRET
|
|
echo $SESSION_SECRET
|
|
|
|
# Try development build instead
|
|
make build
|
|
```
|
|
|
|
#### Kubernetes Issues
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# View real-time logs
|
|
docker-compose -f docker/docker-compose.yaml logs -f
|
|
|
|
# Monitor resource usage
|
|
docker stats
|
|
```
|
|
|
|
### Kubernetes Deployment
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Pull latest changes
|
|
git pull
|
|
|
|
# Rebuild and restart
|
|
make deploy-local
|
|
```
|
|
|
|
### Update Production Deployment
|
|
|
|
```bash
|
|
# Pull latest changes
|
|
git pull
|
|
|
|
# Build and deploy
|
|
make deploy-prod-quick
|
|
|
|
# Or with custom configuration
|
|
make deploy-prod-configured
|
|
```
|
|
|
|
### Backup Data
|
|
|
|
#### Docker CouchDB
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Access CouchDB pod
|
|
kubectl exec -n rxminder-prod -it <couchdb-pod> -- bash
|
|
|
|
# Use CouchDB backup tools
|
|
# Or backup persistent volume
|
|
```
|
|
|
|
## 🚀 Quick Commands Reference
|
|
|
|
```bash
|
|
# 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](deployment/PRODUCTION_BUILD.md) - Detailed production configuration
|
|
- [Docker Configuration](deployment/DOCKER_IMAGE_CONFIGURATION.md) - Docker setup details
|
|
- [Database Service](development/DATABASE.md) - Database configuration
|
|
- [Main README](../README.md) - Complete project overview
|
|
|
|
---
|
|
|
|
**Last Updated:** January 2024
|
|
**Status:** Ready for deployment
|