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)

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

### Production Build

```bash
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

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

#### Database Configuration

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

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

```bash
# 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:

```bash
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:

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

# Edit with your production values
nano .env.production
```

Then build:

```bash
NODE_ENV=production make build-prod
```

### Method 3: Generate Production Config

Use the unified configuration system:

```bash
# 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

```bash
# Check current configuration
make config-debug

# Validate configuration
make validate-config
```

### 2. Set Production Environment

```bash
export NODE_ENV=production
```

### 3. Configure Secrets

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

### 4. Build Application

```bash
make build-prod
```

### 5. Verify Build

```bash
# Check dist directory
ls -la dist/

# Test build locally
make preview
```

## Docker Production Build

### Using Docker Compose

```bash
# 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

```bash
# Build production Docker images
make docker-build

# With production environment
NODE_ENV=production make docker-build
```

## Kubernetes Production Deployment

### 1. Generate Kubernetes Configuration

```bash
# Generate production K8s configs
make generate-config-prod
```

### 2. Apply Configuration

```bash
# Deploy to production
make deploy-prod

# Check deployment status
make status-prod
```

### 3. Verify Deployment

```bash
# Check differences before applying
make diff-prod

# Validate configurations
make validate-k8s
```

## Environment-Specific Builds

### Development

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

### Staging

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

### Production

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

## Troubleshooting

### Error: "JWT_SECRET must be changed in production"

```bash
# 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"

```bash
# 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

```yaml
- 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

```yaml
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

```bash
# 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

```bash
# 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

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

---

## Related Documentation

- [Deployment Guide](DEPLOYMENT.md) - General deployment instructions
- [Docker Configuration](DOCKER_IMAGE_CONFIGURATION.md) - Docker setup
- [Environment Variables](../ENVIRONMENT_VARIABLES.md) - All environment variables
- [Security](../development/SECURITY.md) - Security guidelines

---

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