Rustelo/book/configuration

Rustelo Configuration

Welcome to the Rustelo Configuration documentation! This comprehensive guide covers all aspects of configuring your Rustelo application for different environments and use cases.

📋 Configuration Overview

Rustelo uses a powerful, modular configuration system that allows you to:

• Environment-specific configurations - Different settings for dev, staging, production
• Feature-based configuration - Enable/disable features as needed
• Secure secret management - Environment variables for sensitive data
• Modular composition - Build configurations from reusable components
• Runtime validation - Ensure configurations are valid before startup

🎯 Quick Start

Basic Configuration

# Build development configuration
./config/scripts/build-config.sh dev

# Build production configuration
./config/scripts/build-config.sh prod config.prod.toml

# View configuration status
./config/scripts/debug-manage.sh status

Environment Variables

# Create .env file
cat > .env << EOF
DATABASE_URL=sqlite//:app.db
SESSION_SECRET=your-session-secret
JWT_SECRET=your-jwt-secret
EOF

# Load environment
source .env

📖 Configuration Guides

Core Configuration

• Database Configuration - Database connections, migrations, and pooling
• Environment Variables - Managing secrets and environment-specific settings
• Security Configuration - Authentication, authorization, and security settings
• Performance Configuration - Optimization and performance tuning

Advanced Configuration

• Feature Configuration - Enable/disable application features
• Configuration Files - Understanding configuration file structure
• Configuration Files - Understanding configuration file structure
• Security Configuration - Security settings and best practices

🏗️ Configuration Architecture

File Structure

config/
├── base/                    # Base configurations
│   ├── dev.toml            # Development base
│   ├── prod.toml           # Production base
│   └── example.toml        # Example/documentation
├── features/               # Feature-specific configs
│   ├── auth/               # Authentication features
│   ├── content/            # Content management
│   ├── email/              # Email system
│   ├── metrics/            # Monitoring & metrics
│   └── tls/                # TLS/SSL configuration
└── scripts/                # Configuration tools
    ├── build-config.sh     # Build configurations
    ├── debug-manage.sh     # Debug and management
    └── validate-config.sh  # Validation tools

Configuration Layers

1. Base Configuration - Core application settings
2. Feature Configuration - Feature-specific settings
3. Environment Variables - Runtime secrets and overrides
4. Command Line Arguments - Runtime parameter overrides

🔧 Configuration Types

Application Configuration

[app]
name = "My Rustelo App"
version = "1.0.0"
environment = "development"
debug = true

[server]
host = "127.0.0.1"
port = 3030
workers = 4

Database Configuration

[database]
url = "${DATABASE_URL}"
max_connections = 10
min_connections = 2
connect_timeout = 30
idle_timeout = 300

Feature Configuration

[features]
auth = true
content_db = true
email = false
metrics = true
tls = false

Security Configuration

[security]
session_secret = "${SESSION_SECRET}"
jwt_secret = "${JWT_SECRET}"
csrf_protection = true
rate_limiting = true
secure_cookies = true

🌍 Environment Management

Development Environment

# Development configuration
DATABASE_URL=sqlite//:dev.db
SESSION_SECRET=dev-session-secret
LOG_LEVEL=debug
ENABLE_HOT_RELOAD=true

Production Environment

# Production configuration
DATABASE_URL=postgresql://user:pass@host:5432/db
SESSION_SECRET=secure-random-secret
LOG_LEVEL=info
ENABLE_HOT_RELOAD=false
DOMAIN=myapp.com

Staging Environment

# Staging configuration
DATABASE_URL=postgresql://user:pass@staging-host:5432/db
SESSION_SECRET=staging-secret
LOG_LEVEL=info
ENABLE_DEBUG=false

🔐 Secret Management

Environment Variables

# Required secrets
export SESSION_SECRET=$(openssl rand -base64 32)
export JWT_SECRET=$(openssl rand -base64 32)
export DATABASE_URL="postgresql://user:pass@host:5432/db"

# Optional secrets
export SMTP_PASSWORD="your-smtp-password"
export OAUTH_CLIENT_SECRET="your-oauth-secret"

Secret Management Tools

# Generate secure secrets
./config/scripts/generate-secrets.sh

# Encrypt/decrypt configuration
./config/scripts/encrypt-config.sh
./config/scripts/decrypt-config.sh

# Validate secrets
./config/scripts/validate-secrets.sh

🎛️ Feature Management

Enabling Features

[features]
# Authentication system
auth = true

# Content management
content_db = true

# Email functionality
email = true

# Monitoring and metrics
metrics = true

# TLS/SSL support
tls = true

Feature Dependencies

[features.auth]
enabled = true
dependencies = ["crypto", "database"]

[features.content_db]
enabled = true
dependencies = ["database", "auth"]

[features.email]
enabled = false
dependencies = ["auth"]

🚀 Configuration Best Practices

Development Best Practices

• Use SQLite for development databases
• Enable debug logging
• Use relaxed security settings
• Enable hot reloading
• Use local file storage

Production Best Practices

• Use PostgreSQL for production databases
• Enable minimal logging
• Use strict security settings
• Disable debug features
• Use cloud storage services

Security Best Practices

• Never commit secrets to version control
• Use environment variables for sensitive data
• Rotate secrets regularly
• Use strong encryption keys
• Enable HTTPS in production

📊 Configuration Validation

Validation Scripts

# Validate current configuration
./config/scripts/validate-config.sh

# Validate specific environment
./config/scripts/validate-config.sh prod

# Check configuration completeness
./config/scripts/check-config.sh

Schema Validation

[validation]
strict_mode = true
required_fields = ["database.url", "security.session_secret"]
allowed_environments = ["dev", "staging", "prod"]

🔄 Configuration Updates

Runtime Updates

# Reload configuration (if supported)
kill -HUP $(pidof rustelo-server)

# Update feature flags
./config/scripts/update-features.sh --enable email

# Apply configuration changes
./config/scripts/apply-config.sh

Configuration Deployment

# Deploy configuration to staging
./config/scripts/deploy-config.sh staging

# Deploy configuration to production
./config/scripts/deploy-config.sh prod

# Rollback configuration
./config/scripts/rollback-config.sh

🧪 Testing Configuration

Configuration Tests

# Test configuration validity
just config-test

# Test feature configurations
just config-test-features

# Test environment configurations
just config-test-env prod

Integration Tests

# Test configuration integration
cargo test --test config_integration

# Test feature integration
cargo test --test feature_integration

🔍 Troubleshooting

Common Issues

Configuration Not Found

# Check configuration file exists
ls -la config.toml

# Rebuild configuration
./config/scripts/build-config.sh dev

Environment Variables Missing

# Check environment variables
env | grep -E "(DATABASE_URL|SESSION_SECRET|JWT_SECRET)"

# Load environment file
source .env

Feature Configuration Conflicts

# Check feature dependencies
./config/scripts/debug-manage.sh check-features

# Resolve conflicts
./config/scripts/resolve-conflicts.sh

Debug Tools

# Debug configuration
./config/scripts/debug-manage.sh debug

# Show configuration tree
./config/scripts/debug-manage.sh tree

# Validate configuration
./config/scripts/debug-manage.sh validate

📚 Configuration Examples

Minimal Configuration

[app]
name = "My App"
environment = "development"

[database]
url = "sqlite://app.db"

[features]
auth = true

Full-Featured Configuration

[app]
name = "Production App"
environment = "production"
debug = false

[server]
host = "0.0.0.0"
port = 443
workers = 8

[database]
url = "${DATABASE_URL}"
max_connections = 20
ssl_mode = "require"

[features]
auth = true
content_db = true
email = true
metrics = true
tls = true

[security]
session_secret = "${SESSION_SECRET}"
jwt_secret = "${JWT_SECRET}"
csrf_protection = true
rate_limiting = true
secure_cookies = true

🎯 Next Steps

1. Database Configuration - Set up your database
2. Environment Variables - Configure environment-specific settings
3. Security Configuration - Secure your application
4. Feature Configuration - Enable the features you need
5. Performance Configuration - Optimize for production

🆘 Getting Help

• Common Issues - Solutions to common problems
• Configuration Files Guide - Understanding configuration structure
• Environment Guide - Environment variable management
• Community Support - Discord, GitHub Issues, Stack Overflow

---

Master your Rustelo configuration! 🦀⚙️