515c9343f4
Some checks failed
CI/CD Pipeline / Test Suite (push) Has been cancelled
CI/CD Pipeline / Security Audit (push) Has been cancelled
CI/CD Pipeline / Build Docker Image (push) Has been cancelled
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
CI/CD Pipeline / Performance Benchmarks (push) Has been cancelled
CI/CD Pipeline / Cleanup (push) Has been cancelled
335 lines
9.9 KiB
Markdown
335 lines
9.9 KiB
Markdown
# 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. |