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

```bash
# 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](../configuration/environment.md)
- 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:

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

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

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

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

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

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

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

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

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

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

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

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

### Integration Testing

Test the complete system:

```bash
# 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**
   ```bash
   # Check for missing variables
   ./scripts/check-env.sh production
   ```

2. **Invalid Variable Formats**
   ```bash
   # Validate variable formats
   echo $DATABASE_URL | grep -E "^postgresql://"
   ```

3. **Permission Issues**
   ```bash
   # Check file permissions for certificates
   ls -la /etc/ssl/certs/yourapp.crt
   ```

### Debug Commands

```bash
# 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](../configuration/environment.md)
- Check the [Troubleshooting Guide](../troubleshooting/common.md)
- 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