2f0f807331
- Add complete dark mode system with theme context and toggle - Implement dark mode toggle component in navigation menu - Add client-side routing with SSR-safe signal handling - Fix language selector styling for better dark mode compatibility - Add documentation system with mdBook integration - Improve navigation menu with proper external/internal link handling - Add comprehensive project documentation and configuration - Enhance theme system with localStorage persistence - Fix arena panic issues during server-side rendering - Add proper TypeScript configuration and build optimizations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
309 lines
6.4 KiB
Markdown
309 lines
6.4 KiB
Markdown
# 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
|