Rustelo/book/configuration/README.md

# 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
```bash
# 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
```bash
# 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.md)** - Database connections, migrations, and pooling
- **[Environment Variables](./environment.md)** - Managing secrets and environment-specific settings
- **[Security Configuration](./security.md)** - Authentication, authorization, and security settings
- **[Performance Configuration](./performance.md)** - Optimization and performance tuning

### Advanced Configuration
- **[Feature Configuration](./features.md)** - Enable/disable application features
- **[Configuration Files](./files.md)** - Understanding configuration file structure
- **[Configuration Files](./files.md)** - Understanding configuration file structure
- **[Security Configuration](./security.md)** - 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
```toml
[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
```toml
[database]
url = "${DATABASE_URL}"
max_connections = 10
min_connections = 2
connect_timeout = 30
idle_timeout = 300
```

### Feature Configuration
```toml
[features]
auth = true
content_db = true
email = false
metrics = true
tls = false
```

### Security Configuration
```toml
[security]
session_secret = "${SESSION_SECRET}"
jwt_secret = "${JWT_SECRET}"
csrf_protection = true
rate_limiting = true
secure_cookies = true
```

## 🌍 Environment Management

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

### Production Environment
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```toml
[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
```toml
[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
```bash
# 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
```toml
[validation]
strict_mode = true
required_fields = ["database.url", "security.session_secret"]
allowed_environments = ["dev", "staging", "prod"]
```

## 🔄 Configuration Updates

### Runtime Updates
```bash
# 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
```bash
# 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
```bash
# Test configuration validity
just config-test

# Test feature configurations
just config-test-features

# Test environment configurations
just config-test-env prod
```

### Integration Tests
```bash
# Test configuration integration
cargo test --test config_integration

# Test feature integration
cargo test --test feature_integration
```

## 🔍 Troubleshooting

### Common Issues

#### Configuration Not Found
```bash
# Check configuration file exists
ls -la config.toml

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

#### Environment Variables Missing
```bash
# Check environment variables
env | grep -E "(DATABASE_URL|SESSION_SECRET|JWT_SECRET)"

# Load environment file
source .env
```

#### Feature Configuration Conflicts
```bash
# Check feature dependencies
./config/scripts/debug-manage.sh check-features

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

### Debug Tools
```bash
# 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
```toml
[app]
name = "My App"
environment = "development"

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

[features]
auth = true
```

### Full-Featured Configuration
```toml
[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](./database.md)** - Set up your database
2. **[Environment Variables](./environment.md)** - Configure environment-specific settings
3. **[Security Configuration](./security.md)** - Secure your application
4. **[Feature Configuration](./features.md)** - Enable the features you need
5. **[Performance Configuration](./performance.md)** - Optimize for production

## 🆘 Getting Help

- **[Common Issues](../troubleshooting/common.md)** - Solutions to common problems
- **[Configuration Files Guide](./files.md)** - Understanding configuration structure
- **[Environment Guide](./environment.md)** - Environment variable management
- **Community Support** - Discord, GitHub Issues, Stack Overflow

---

**Master your Rustelo configuration!** 🦀⚙️