Rustelo/book/reference/env-migration.md

Environment Variable Migration Guide

This guide covers how to migrate environment variables between different versions of Rustelo and different deployment environments.

Overview

Environment variable migrations may be necessary when:

• Upgrading to a new version of Rustelo
• Moving between deployment environments (dev → staging → production)
• Changing configuration structure
• Adding or removing features
• Updating security requirements

Migration Process

1. Audit Current Environment Variables

First, document your current environment variables:

# List all Rustelo-related environment variables
env | grep -E "(RUSTELO|DATABASE|SMTP|JWT|SESSION)" > current_env.txt

2. Compare with New Requirements

Review the environment variable documentation for the target version:

• Environment Variables Guide
• Version-specific release notes
• Feature documentation

3. Create Migration Plan

Document the changes needed:

• Variables to add
• Variables to update
• Variables to remove
• Variables to rename

4. Update Environment Variables

Update your environment configuration:

# Development
cp .env.development .env.development.backup
# Update .env.development with new variables

# Production
# Update environment variables in your deployment system

5. Validate Configuration

Test the new environment variables:

# Validate configuration loading
./rustelo-server --check-config

# Test specific features
./rustelo-server --test-feature auth
./rustelo-server --test-feature email

Common Migration Scenarios

Adding New Features

When enabling new features, you may need to add:

# Email feature
SMTP_HOST=smtp.gmail.com
SMTP_USERNAME=your-app@gmail.com
SMTP_PASSWORD=your-app-password
FROM_EMAIL=noreply@yourapp.com

# Metrics feature
PROMETHEUS_ENDPOINT=/metrics
GRAFANA_URL=https://grafana.yourapp.com

# TLS feature
TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt
TLS_KEY_FILE=/etc/ssl/private/yourapp.key

Security Updates

Security updates may require new secrets:

# New encryption key
ENCRYPTION_KEY=your-base64-encoded-key

# Updated JWT configuration
JWT_SECRET=your-new-jwt-secret
JWT_ALGORITHM=HS256

# Enhanced session security
SESSION_SECRET=your-new-session-secret
CSRF_SECRET=your-csrf-secret

Database Migrations

Database configuration updates:

# Connection pool updates
DATABASE_MAX_CONNECTIONS=20
DATABASE_SSL_MODE=require

# New database features
DATABASE_QUERY_TIMEOUT=30000
DATABASE_PREPARED_STATEMENT_CACHE_SIZE=256

Environment-Specific Considerations

Development Environment

Development environments typically require:

• Relaxed security settings
• Local service URLs
• Debug-friendly configuration

RUSTELO_ENV=development
RUSTELO_DEBUG=true
DATABASE_URL=sqlite//:dev_database.db
SMTP_HOST=localhost
SMTP_PORT=1025

Staging Environment

Staging environments should mirror production:

• Production-like security
• Test service configurations
• Monitoring enabled

RUSTELO_ENV=staging
DATABASE_URL=postgresql://user:pass@staging-db:5432/app
FRONTEND_URL=https://staging.yourapp.com

Production Environment

Production environments require:

• Maximum security
• Performance optimization
• Full monitoring

RUSTELO_ENV=production
DATABASE_URL=postgresql://user:pass@prod-db:5432/app
FRONTEND_URL=https://yourapp.com
TLS_ENABLED=true

Rollback Procedures

Environment Variable Rollback

If migration fails, rollback environment variables:

# Restore from backup
cp .env.production.backup .env.production

# Or restore specific variables
export DATABASE_URL="previous-database-url"
export SESSION_SECRET="previous-session-secret"

Configuration Rollback

Rollback to previous configuration:

# Restore configuration from backup
./config/scripts/manage-config.sh restore backup_file.toml

# Rebuild configuration
./config/scripts/build-config.sh prod config.prod.toml

Validation and Testing

Environment Variable Validation

Validate environment variables:

# Check required variables are set
./scripts/check-env.sh production

# Validate variable formats
./scripts/validate-env.sh production

Integration Testing

Test the complete system:

# Run integration tests
cargo test --features integration

# Test specific components
cargo test auth_tests
cargo test email_tests
cargo test database_tests

Version-Specific Migrations

v1.0.0 to v1.1.0

No breaking changes in environment variables.

v1.1.0 to v1.2.0 (Planned)

Potential changes:

• New security-related variables
• Enhanced monitoring variables
• Performance tuning variables

Best Practices

Secret Management

• Use secure secret management systems
• Rotate secrets regularly
• Never commit secrets to version control
• Use different secrets for each environment

Documentation

• Document all environment variables
• Maintain migration logs
• Update deployment documentation
• Train team members on new variables

Testing

• Test migrations in staging first
• Validate all features after migration
• Monitor application health
• Have rollback plans ready

Troubleshooting

Common Issues

1. Missing Environment Variables

   # Check for missing variables
   ./scripts/check-env.sh production
   

2. Invalid Variable Formats

   # Validate variable formats
   echo $DATABASE_URL | grep -E "^postgresql://"
   

3. Permission Issues

   # Check file permissions for certificates
   ls -la /etc/ssl/certs/yourapp.crt
   

Debug Commands

# Show loaded environment variables
./rustelo-server --show-env

# Test configuration loading
./rustelo-server --check-config

# Validate specific features
./rustelo-server --validate-feature auth

Getting Help

For environment variable migration assistance:

• Review the Environment Variables Guide
• Check the Troubleshooting Guide
• Consult the community forums
• Contact technical support

Migration Checklist

• Backup current environment variables
• Review new requirements
• Create migration plan
• Update development environment
• Test in staging environment
• Validate all features
• Update production environment
• Monitor application health
• Update documentation
• Train team members