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:

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

Build configuration for production:

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

2. Using the Management Script

The management script provides comprehensive configuration operations:

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

# 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

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

Environment Variables

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

[database]
url = "${DATABASE_URL}"

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

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

Creating New Features

Using the Template Command

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

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

Manual Creation

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

Example feature structure:

# 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

# 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

Invalid TOML Syntax
- Check for missing quotes, brackets, or commas
- Validate individual files before building
Missing Environment Variables
- Ensure all required environment variables are set
- Check variable names for typos
Feature Conflicts
- Review feature configurations for conflicting settings
- Use the diff command to compare configurations

Debug Mode

Enable debug output for detailed information:

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

Or with the management script:

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

Advanced Usage

Custom Configuration Directories

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

Validation Only

# 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

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

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

Contributing

When adding new features or modifying existing ones:

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

License

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

README.md

Rustelo Configuration System

Overview