Rustelo/config/README.md

# Rustelo Configuration System

A modular, environment-aware configuration system that separates concerns by features and environments.

## Overview

The Rustelo configuration system provides a flexible way to manage application configurations across different environments (development, production, example) while maintaining feature-specific settings in separate modules.

## Directory Structure

```
config/
├── base/                    # Base configurations for each environment
│   ├── dev.toml            # Development base settings
│   ├── prod.toml           # Production base settings
│   └── example.toml        # Example/template base settings
├── features/               # Feature-specific configurations
│   ├── auth/               # Authentication feature
│   │   ├── dev.toml        # Auth settings for development
│   │   ├── prod.toml       # Auth settings for production
│   │   └── example.toml    # Auth example settings
│   ├── email/              # Email feature
│   │   ├── dev.toml        # Email settings for development
│   │   ├── prod.toml       # Email settings for production
│   │   └── example.toml    # Email example settings
│   ├── tls/                # TLS/SSL feature
│   │   ├── dev.toml        # TLS settings for development
│   │   ├── prod.toml       # TLS settings for production
│   │   └── example.toml    # TLS example settings
│   ├── content/            # Content management feature
│   │   ├── dev.toml        # Content settings for development
│   │   ├── prod.toml       # Content settings for production
│   │   └── example.toml    # Content example settings
│   └── metrics/            # Metrics and monitoring feature
│       ├── dev.toml        # Metrics settings for development
│       ├── prod.toml       # Metrics settings for production
│       └── example.toml    # Metrics example settings
├── scripts/                # Configuration management scripts
│   ├── build-config.sh     # Shell script to build configurations
│   └── manage-config.sh    # Configuration management utility
├── backups/                # Backup configurations (auto-created)
└── README.md              # This file
```

## Quick Start

### 1. Build Configuration

Build a complete configuration for development:

```bash
./config/scripts/build-config.sh dev
```

Build configuration for production:

```bash
./config/scripts/build-config.sh prod config.prod.toml
```

### 2. Using the Management Script

The management script provides comprehensive configuration operations:

```bash
# Build configurations
./config/scripts/manage-config.sh build dev
./config/scripts/manage-config.sh build prod config.prod.toml

# Validate configurations
./config/scripts/manage-config.sh validate dev
./config/scripts/manage-config.sh validate prod

# List available features and environments
./config/scripts/manage-config.sh list-features
./config/scripts/manage-config.sh list-environments

# Compare configurations between environments
./config/scripts/manage-config.sh diff dev prod

# Create backups
./config/scripts/manage-config.sh backup prod

# Show configuration status
./config/scripts/manage-config.sh status
```

### 3. Using Python Builder (Advanced)

For more advanced TOML handling and validation:

```bash
# Build configuration
./config/scripts/build-config.sh dev
./config/scripts/build-config.sh prod config.prod.toml

# Validate only (no output file)
CONFIG_VALIDATE_ONLY=1 ./config/scripts/build-config.sh dev
```

## Configuration Structure

### Base Configurations

Base configurations (`config/base/`) contain core settings that apply to all features:

- **Server settings**: Protocol, host, port, workers
- **Database settings**: Connection strings, pool sizes
- **Session management**: Cookie settings, timeouts
- **CORS settings**: Allowed origins, methods, headers
- **Security settings**: CSRF, rate limiting, encryption
- **Logging settings**: Levels, formats, outputs

### Feature Configurations

Feature configurations (`config/features/`) contain settings specific to individual features:

- **Authentication**: JWT, OAuth, password policies, session management
- **Email**: SMTP, templates, queues, validation
- **TLS**: Certificates, protocols, security settings
- **Content**: Management, processing, validation, caching
- **Metrics**: Collection, export, alerting, performance tracking

### Environment-Specific Settings

Each environment has different optimization focuses:

#### Development (`dev.toml`)
- Relaxed security settings
- Verbose logging
- Hot reloading enabled
- Mock services
- Extended timeouts
- Debug features enabled

#### Production (`prod.toml`)
- Strict security settings
- Optimized performance
- Minimal logging
- Real services
- Short timeouts
- Debug features disabled

#### Example (`example.toml`)
- Complete feature documentation
- All available options shown
- Best practice configurations
- Commented examples

## How Configuration Building Works

1. **Load Base Configuration**: The base configuration for the target environment is loaded first
2. **Load Feature Configurations**: All available feature configurations for the environment are loaded
3. **Merge Configurations**: Features are merged into the base configuration using deep merging
4. **Add Build Information**: Metadata about the build process is added
5. **Validate Configuration**: The final configuration is validated for correctness
6. **Write Output**: The complete configuration is written to the output file

## Environment Variables

Configuration files support environment variable substitution using `${VARIABLE_NAME}` syntax:

```toml
[database]
url = "${DATABASE_URL}"

[auth.jwt]
secret = "${JWT_SECRET}"

[email.smtp]
password = "${SMTP_PASSWORD}"
```

## Creating New Features

### Using the Template Command

```bash
./config/scripts/manage-config.sh template my_feature
```

This creates a new feature directory with template files for all environments.

### Manual Creation

1. Create a new directory under `config/features/`
2. Create environment-specific TOML files (`dev.toml`, `prod.toml`, `example.toml`)
3. Define feature-specific settings in each file

Example feature structure:

```toml
# config/features/my_feature/dev.toml
[features]
my_feature = true

[my_feature]
enabled = true
debug_mode = true
# ... other settings
```

## Configuration Validation

The system includes built-in validation for:

- **TOML Syntax**: Ensures valid TOML structure
- **Required Sections**: Validates presence of essential configuration sections
- **Value Types**: Checks that configuration values are of expected types
- **Value Ranges**: Validates that numeric values are within acceptable ranges
- **Dependencies**: Ensures required dependencies are available when features are enabled

## Best Practices

### 1. Environment-Specific Optimization

- **Development**: Prioritize developer experience and debugging
- **Production**: Prioritize security, performance, and reliability
- **Example**: Show all available options with documentation

### 2. Feature Independence

- Keep feature configurations independent of each other
- Use feature flags to enable/disable functionality
- Provide sensible defaults for all settings

### 3. Security

- Never commit sensitive values to version control
- Use environment variables for secrets
- Implement proper validation for security-critical settings

### 4. Documentation

- Document all configuration options
- Provide examples for complex settings
- Include units and ranges for numeric values

## Backup and Recovery

### Automatic Backups

The build scripts automatically create backups of existing configurations before generating new ones:

```
config/backups/config_prod_20231201_143022.toml
```

### Manual Backups

```bash
# Create backup
./config/scripts/manage-config.sh backup prod

# Restore from backup
./config/scripts/manage-config.sh restore config/backups/config_prod_20231201_143022.toml
```

## Troubleshooting

### Common Issues

1. **Invalid TOML Syntax**
   - Check for missing quotes, brackets, or commas
   - Validate individual files before building

2. **Missing Environment Variables**
   - Ensure all required environment variables are set
   - Check variable names for typos

3. **Feature Conflicts**
   - Review feature configurations for conflicting settings
   - Use the diff command to compare configurations

### Debug Mode

Enable debug output for detailed information:

```bash
CONFIG_DEBUG=1 ./config/scripts/build-config.sh dev
```

Or with the management script:

```bash
./config/scripts/manage-config.sh --debug build dev
```

## Advanced Usage

### Custom Configuration Directories

```bash
CONFIG_DIR=/path/to/custom/config ./config/scripts/build-config.sh dev
```

### Validation Only

```bash
# Validate without building
./config/scripts/manage-config.sh validate dev

# Shell script validation
CONFIG_VALIDATE_ONLY=1 ./config/scripts/build-config.sh prod
```

### Dry Run Mode

```bash
# See what would be done without executing
./config/scripts/manage-config.sh --dry-run build prod
```

## Integration with Rustelo

The generated configuration files are designed to work seamlessly with Rustelo's configuration system:

1. **Feature Flags**: Control which features are compiled and enabled
2. **Environment Detection**: Automatic environment detection and configuration loading
3. **Hot Reloading**: Support for configuration hot reloading in development
4. **Validation**: Built-in configuration validation at runtime

## Contributing

When adding new features or modifying existing ones:

1. Update all three environment files (`dev.toml`, `prod.toml`, `example.toml`)
2. Add appropriate validation rules
3. Update documentation
4. Test configuration building and validation
5. Add examples to the example configuration

## License

This configuration system is part of the Rustelo project and follows the same license terms.