rxminder/docs/deployment/PRODUCTION_BUILD.md

Production Build Guide

This guide explains how to properly configure and build the RxMinder application for production deployment.

Overview

The RxMinder application has strict security validations that prevent production builds with default or insecure configurations. This ensures that production deployments are properly secured.

Build Commands

Development Build (Default)

make build                    # Builds with development configuration
NODE_ENV=development bun run build

Production Build

make build-prod              # Builds with production configuration
bun run build                # Requires proper production environment setup

Production Configuration Requirements

Required Environment Variables

Before running a production build, you must set the following environment variables:

Authentication Secrets

# Required: Change these from defaults
JWT_SECRET=your-secure-jwt-secret-here
SESSION_SECRET=your-secure-session-secret-here

Database Configuration

# Required for production deployments
VITE_COUCHDB_URL=https://your-couchdb-instance.com
COUCHDB_USER=your-couchdb-username
COUCHDB_PASSWORD=your-couchdb-password

Email Configuration (Optional)

# Mailgun configuration
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=your-domain.com
MAILGUN_FROM_NAME="Your App Name"
MAILGUN_FROM_EMAIL=noreply@your-domain.com

OAuth Configuration (Optional)

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Configuration Methods

Method 1: Environment Variables

Set environment variables directly:

export JWT_SECRET="your-secure-jwt-secret"
export SESSION_SECRET="your-secure-session-secret"
export VITE_COUCHDB_URL="https://your-couchdb.com"
make build-prod

Method 2: .env File

Create a .env.production file:

# Copy and modify the example
cp .env.example .env.production

# Edit with your production values
nano .env.production

Then build:

NODE_ENV=production make build-prod

Method 3: Generate Production Config

Use the unified configuration system:

# Generate production configuration
make generate-config-prod

# Then build
make build-prod

Security Validations

The build process validates the following:

Critical Errors (Will Fail Build)

• JWT_SECRET must not be the default value in production
• SESSION_SECRET must not be the default value in production

Warnings (Will Show But Allow Build)

• Missing OAuth client IDs (OAuth will be disabled)
• Missing email configuration (Email features disabled)
• Using default database URL (Will use mock database)

Production Build Process

1. Validate Configuration

# Check current configuration
make config-debug

# Validate configuration
make validate-config

2. Set Production Environment

export NODE_ENV=production

3. Configure Secrets

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

4. Build Application

make build-prod

5. Verify Build

# Check dist directory
ls -la dist/

# Test build locally
make preview

Docker Production Build

Using Docker Compose

# Build production image
docker-compose -f docker/docker-compose.prod.yml build

# Deploy with production configuration
docker-compose -f docker/docker-compose.prod.yml up -d

Using Makefile

# Build production Docker images
make docker-build

# With production environment
NODE_ENV=production make docker-build

Kubernetes Production Deployment

1. Generate Kubernetes Configuration

# Generate production K8s configs
make generate-config-prod

2. Apply Configuration

# Deploy to production
make deploy-prod

# Check deployment status
make status-prod

3. Verify Deployment

# Check differences before applying
make diff-prod

# Validate configurations
make validate-k8s

Environment-Specific Builds

Development

NODE_ENV=development make build
# Uses development defaults, allows insecure configurations

Staging

NODE_ENV=staging make build-prod
# Uses staging configuration with production validations

Production

NODE_ENV=production make build-prod
# Requires all production security validations

Troubleshooting

Error: "JWT_SECRET must be changed in production"

# Solution: Set a secure JWT secret
export JWT_SECRET=$(openssl rand -base64 32)
export SESSION_SECRET=$(openssl rand -base64 32)
make build-prod

Error: "Configuration validation failed"

# Check what's missing
make validate-config

# Debug current configuration
make config-debug

# Generate complete configuration
make generate-config-prod

Build Succeeds But Features Missing

Check warnings in build output:

• Missing OAuth: Set GOOGLE_CLIENT_ID and GITHUB_CLIENT_ID
• Missing email: Set MAILGUN_API_KEY and MAILGUN_DOMAIN
• Mock database: Set VITE_COUCHDB_URL to real database

Security Best Practices

Secret Management

1. Never commit secrets to version control
2. Use environment variables or secure secret management
3. Rotate secrets regularly in production
4. Use different secrets for each environment

Database Security

1. Use HTTPS for CouchDB connections
2. Configure authentication with strong passwords
3. Limit database access to application only
4. Regular backups and security updates

OAuth Security

1. Restrict redirect URIs to your domains only
2. Use HTTPS for OAuth redirects
3. Regularly review OAuth application permissions
4. Monitor OAuth usage for suspicious activity

CI/CD Integration

GitHub Actions Example

- name: Build Production
  env:
    JWT_SECRET: ${{ secrets.JWT_SECRET }}
    SESSION_SECRET: ${{ secrets.SESSION_SECRET }}
    VITE_COUCHDB_URL: ${{ secrets.COUCHDB_URL }}
  run: make build-prod

GitLab CI Example

build:production:
  variables:
    NODE_ENV: 'production'
  script:
    - export JWT_SECRET="$PRODUCTION_JWT_SECRET"
    - export SESSION_SECRET="$PRODUCTION_SESSION_SECRET"
    - make build-prod

Performance Optimization

Bundle Analysis

# Build with bundle analysis
ANALYZE=true make build-prod

# Check bundle size
ls -lh dist/assets/

Code Splitting

The build automatically splits code for optimal loading:

• Main application bundle
• Vendor dependencies
• Dynamic imports for large features

Compression

Production builds include:

• Gzip compression
• Minification
• Tree shaking
• Dead code elimination

Deployment Verification

Health Checks

After deployment, verify:

1. Application loads without errors
2. Database connection works
3. Authentication functions properly
4. Email notifications work (if configured)
5. OAuth login works (if configured)

Performance Checks

1. Initial load time < 3 seconds
2. Bundle size reasonable (check warnings)
3. No console errors in browser
4. Proper caching headers set

Rollback Procedures

Quick Rollback

# Rollback Kubernetes deployment
kubectl rollout undo deployment/rxminder -n rxminder-prod

# Rollback Docker deployment
docker-compose -f docker/docker-compose.prod.yml down
# Deploy previous image version

Configuration Rollback

# Revert to previous configuration
git checkout HEAD~1 -- .env.production
make build-prod
make deploy-prod

---

Related Documentation

• Deployment Guide - General deployment instructions
• Docker Configuration - Docker setup
• Environment Variables - All environment variables
• Security - Security guidelines

---

Last Updated: January 2024
Version: 2.0.0
Status: Production Ready