Skip to Content
Nextra 2 Alpha
User GuideRhema Configuration Management System

Rhema Configuration Management System

Overview

The Rhema Configuration Management System provides comprehensive configuration management capabilities for the Rhema CLI, including global settings, repository-specific configurations, security features, and advanced management tools.

Architecture

Configuration Hierarchy

Global Configuration (User-wide settings) ├── User Preferences ├── Application Settings ├── Environment Configuration ├── Security Settings ├── Performance Settings └── Integration Settings Repository Configuration (Per-repository settings) ├── Repository Information ├── Repository Settings ├── Scope Configuration ├── Workflow Configuration ├── Security Configuration └── Integration Configuration

Configuration Types

  1. Global Configuration: User-wide settings stored in ~/.rhema/config.yaml

  2. Repository Configuration: Per-repository settings stored in .rhema/config.yaml

  3. Scope Configuration: Per-scope settings within repositories

Features

1. Global Configuration Management

User Settings

  • Personal preferences and customization

  • Default editor and output format

  • Color scheme and UI preferences

  • Notification settings

Application Settings

  • Debug mode and logging configuration

  • Telemetry and auto-update settings

  • Feature flags and experimental features

  • Plugin management

Environment Configuration

  • Environment-specific settings (development, testing, staging, production)

  • Path configurations

  • Environment variables management

Security Settings

  • Encryption configuration

  • Authentication and authorization

  • Audit logging

  • Compliance frameworks

Performance Settings

  • Cache configuration

  • Threading and memory settings

  • Network configuration

  • Proxy settings

Integration Settings

  • Git integration

  • IDE integration

  • CI/CD integration

  • Cloud integration

  • External services

2. Repository Configuration Management

Repository Information

  • Repository metadata

  • Owner and visibility settings

  • Tags and descriptions

Repository Settings

  • Default branch configuration

  • Branch protection rules

  • Commit message conventions

  • Code review settings

  • Testing configuration

  • Documentation settings

  • Deployment configuration

Scope Configuration

  • Scope naming conventions

  • Scope templates

  • Inheritance rules

  • Validation rules

Workflow Configuration

  • Workflow types and steps

  • Triggers and conditions

  • Pipeline configuration

Security Configuration

  • Security scanning

  • Access control

  • Secrets management

  • Compliance rules

Integration Configuration

  • CI/CD integration

  • Issue tracking

  • Communication channels

  • Monitoring integration

3. Configuration Security

Encryption

  • Configuration file encryption

  • Key management

  • Secure storage

Access Control

  • Role-based access control

  • Permission management

  • User authentication

Audit Logging

  • Configuration change tracking

  • User activity logging

  • Compliance reporting

Compliance

  • Framework compliance

  • Policy enforcement

  • Reporting and monitoring

4. Configuration Tools

Management Commands

  • rhema config show - Display configuration

  • rhema config edit - Edit configuration

  • rhema config validate - Validate configuration

  • rhema config backup - Backup configuration

  • rhema config restore - Restore configuration

  • rhema config migrate - Migrate configuration

  • rhema config export - Export configuration

  • rhema config import - Import configuration

  • rhema config set - Set configuration value

  • rhema config get - Get configuration value

  • rhema config reset - Reset to defaults

  • rhema config health - Check configuration health

  • rhema config audit - Audit configuration changes

  • rhema config stats - Show configuration statistics

  • rhema config schema - Show configuration schema

  • rhema config documentation - Show configuration documentation

Usage Examples

Global Configuration

# Show global configuration rhema config show global # Edit global configuration rhema config edit global # Set user name rhema config set global user.name "John Doe" # Set user email rhema config set global user.email "john@example.com" # Set default editor rhema config set global user.preferences.default_editor "vim" # Set environment rhema config set global environment.current "development" # Export configuration rhema config export global --format json --output config.json # Import configuration rhema config import global --format json --input config.json # Validate configuration rhema config validate global # Backup configuration rhema config backup global # Check configuration health rhema config health global

Repository Configuration

# Show repository configuration rhema config show repository --path /path/to/repo # Edit repository configuration rhema config edit repository --path /path/to/repo # Set repository name rhema config set repository --path /path/to/repo repository.name "my-project" # Set default branch rhema config set repository --path /path/to/repo settings.default_branch "main" # Export repository configuration rhema config export repository --path /path/to/repo --format yaml --output repo-config.yaml # Import repository configuration rhema config import repository --path /path/to/repo --format yaml --input repo-config.yaml # Validate repository configuration rhema config validate repository --path /path/to/repo # Backup repository configuration rhema config backup repository --path /path/to/repo

Configuration Management

# Validate all configurations rhema config validate all # Backup all configurations rhema config backup all # Migrate all configurations rhema config migrate all # Show configuration statistics rhema config stats all # Audit configuration changes rhema config audit global --since "2024-01-01" # Show configuration schema rhema config schema global # Show configuration documentation rhema config documentation global

Configuration File Formats

Global Configuration (~/.rhema/config.yaml)

version: "1.0.0" user: id: "user123" name: "John Doe" email: "john@example.com" preferences: default_output_format: "yaml" default_editor: "vim" color_scheme: "dark" language: "en" timezone: "UTC" date_format: "YYYY-MM-DD" time_format: "HH:mm:ss" notifications: email_enabled: true desktop_enabled: true sound_enabled: false frequency: "immediate" types: ["errors", "warnings"] ui: theme: "dark" font_size: 14 show_line_numbers: true show_minimap: false word_wrap: true auto_save: true auto_save_interval: 30 application: name: "Rhema CLI" version: "1.0.0" description: "Git-Based Agent Context Protocol CLI" settings: debug_mode: false verbose_logging: false log_level: "info" log_file: null max_log_size: 100 log_rotation_count: 5 telemetry_enabled: true telemetry_endpoint: "https://telemetry.rhema.dev" auto_update_enabled: true update_check_interval: 24 features: experimental_features: false beta_features: false advanced_features: true ai_features: true cloud_features: false collaboration_features: true analytics_features: true plugins: plugin_directory: "~/.rhema/plugins" auto_load_plugins: true enabled_plugins: ["git", "ai", "analytics"] disabled_plugins: [] plugin_settings: {} environment: current: "development" environments: development: name: "Development" description: "Development environment" variables: DEBUG: "true" LOG_LEVEL: "debug" paths: data: "~/.rhema/data/dev" cache: "~/.rhema/cache/dev" settings: {} testing: name: "Testing" description: "Testing environment" variables: DEBUG: "false" LOG_LEVEL: "info" paths: data: "~/.rhema/data/test" cache: "~/.rhema/cache/test" settings: {} staging: name: "Staging" description: "Staging environment" variables: DEBUG: "false" LOG_LEVEL: "warn" paths: data: "~/.rhema/data/staging" cache: "~/.rhema/cache/staging" settings: {} production: name: "Production" description: "Production environment" variables: DEBUG: "false" LOG_LEVEL: "error" paths: data: "~/.rhema/data/prod" cache: "~/.rhema/cache/prod" settings: {} environment_variables: Rhema_HOME: "~/.rhema" Rhema_CONFIG: "~/.rhema/config.yaml" paths: home: "~/.rhema" config: "~/.rhema" data: "~/.rhema/data" cache: "~/.rhema/cache" log: "~/.rhema/logs" temp: "~/.rhema/temp" workspace: null custom: {} security: encryption: enabled: true algorithm: "AES-256-GCM" key_size: 256 kdf: "PBKDF2" salt_size: 32 iteration_count: 100000 key_file: "~/.rhema/keys/master.key" master_password_required: true authentication: method: "password" session_timeout: 60 max_failed_attempts: 5 lockout_duration: 30 require_mfa: false mfa_method: null sso_enabled: false sso_provider: null authorization: rbac_enabled: true default_role: "user" admin_role: "admin" user_role: "user" guest_role: "guest" permission_inheritance: true permission_cache_enabled: true permission_cache_timeout: 15 audit: enabled: true log_level: "info" log_file: "~/.rhema/logs/audit.log" retention_days: 90 events: ["config_change", "auth", "access"] filters: {} compliance: framework: "SOC2" level: "Type II" reporting_enabled: true checks: ["encryption", "access_control", "audit"] rules: {} performance: cache: enabled: true cache_type: "file" cache_size: 1000 cache_ttl: 3600 cache_directory: "~/.rhema/cache" compression_enabled: true encryption_enabled: false threading: max_threads: 8 thread_pool_size: 4 async_runtime_threads: 4 blocking_thread_pool_size: 2 memory: max_memory_usage: 2048 memory_limit: 4096 gc_enabled: true gc_interval: 300 network: connection_timeout: 30 request_timeout: 60 max_connections: 100 keep_alive_enabled: true keep_alive_timeout: 60 proxy: null integrations: git: enabled: true provider: "github" credentials: username: "johndoe" email: "john@example.com" ssh_key_path: "~/.ssh/id_rsa" personal_access_token: null oauth_token: null hooks_enabled: true hooks_directory: null workflow: "github-flow" branch_naming: feature: "feature/{ticket}-{description}" bugfix: "bugfix/{ticket}-{description}" hotfix: "hotfix/{ticket}-{description}" ide: enabled: true supported_ides: ["vscode", "intellij", "vim"] ide_settings: vscode: auto_sync: true extensions: ["rhema-vscode"] intellij: auto_sync: true plugins: ["rhema-intellij"] auto_sync_enabled: true sync_interval: 30 cicd: enabled: false provider: "github-actions" settings: {} auto_deploy_enabled: false deployment_environments: [] cloud: enabled: false provider: "aws" credentials: access_key_id: null secret_access_key: null session_token: null credentials_file: null profile_name: null regions: ["us-east-1"] services: ["s3", "ec2"] external_services: {} custom: {} audit_log: changes: [] created_at: "2024-01-01T00:00:00Z" updated_at: "2024-01-01T00:00:00Z" health: status: "healthy" issues: [] recommendations: [] last_check: "2024-01-01T00:00:00Z" stats: total_configs: 1 global_configs: 1 repository_configs: 0 scope_configs: 0 encrypted_configs: 1 backup_count: 0 last_backup: null validation_errors: 0 migration_pending: 0 updated_at: "2024-01-01T00:00:00Z"

Repository Configuration (.rhema/config.yaml)

version: "1.0.0" repository: name: "my-project" description: "A sample Rhema project" url: "https://github.com/user/my-project" repository_type: "git" owner: "user" visibility: "public" tags: ["web", "api", "rust"] metadata: language: "rust" framework: "actix-web" database: "postgresql" settings: default_branch: "main" branch_protection: protected_branches: ["main", "develop"] require_reviews: true required_reviewers: 2 require_status_checks: true required_status_checks: ["tests", "lint", "security"] require_up_to_date: true allow_force_push: false allow_deletions: false commit_conventions: conventional_commits: true message_template: null types: ["feat", "fix", "docs", "style", "refactor", "test", "chore"] scopes: ["api", "web", "db", "auth"] breaking_change_format: "BREAKING CHANGE: {description}" footer_format: "Closes #{issue}" code_review: required: true auto_assign: true required_reviewers: ["user1", "user2"] guidelines: - "Check for security vulnerabilities" - "Ensure proper error handling" - "Verify test coverage" checklist: - "Code follows style guidelines" - "Tests pass" - "Documentation updated" timeout_hours: 48 testing: framework: "cargo" test_directory: "tests" test_patterns: ["*_test.rs", "test_*.rs"] coverage_requirements: minimum_coverage: 80.0 by_file_type: "*.rs": 85.0 "*.ts": 80.0 exclusions: ["tests/*", "examples/*"] timeout_seconds: 300 parallel: true documentation: documentation_directory: "docs" format: "markdown" auto_generate: true templates: api: "templates/api.md" readme: "templates/readme.md" standards: ["OpenAPI", "Markdown"] deployment: environments: - name: "staging" url: "https://staging.my-project.com" variables: DATABASE_URL: "postgresql://staging" triggers: ["main"] auto_deploy: true - name: "production" url: "https://my-project.com" variables: DATABASE_URL: "postgresql://production" triggers: ["main"] auto_deploy: false strategy: "rolling" rollback: auto_rollback: true triggers: ["health_check_failed"] timeout_minutes: 10 versions_to_keep: 5 health_checks: - name: "api-health" url: "/health" interval_seconds: 30 timeout_seconds: 5 retries: 3 scopes: default_scope_type: "service" naming_convention: "kebab-case" templates: service: "templates/service.yaml" library: "templates/library.yaml" app: "templates/app.yaml" inheritance: enabled: true rules: - name: "global-settings" source_pattern: "global" target_pattern: "*" fields: ["security", "performance"] priority: 1 override_behavior: "allow" validation: enabled: true rules: - name: "scope-naming" pattern: "^[a-z0-9-]+$" message: "Scope names must be lowercase with hyphens" severity: "error" severity: "error" workflow: workflow_type: "git-flow" steps: - name: "validate" step_type: "validation" config: schema_validation: true lint_check: true dependencies: [] timeout_seconds: 300 - name: "test" step_type: "testing" config: framework: "cargo" coverage: true dependencies: ["validate"] timeout_seconds: 600 - name: "build" step_type: "build" config: target: "release" artifacts: ["binary"] dependencies: ["test"] timeout_seconds: 900 triggers: - name: "push" trigger_type: "git_push" conditions: branch: "main" conditions: - name: "has-tests" expression: "file_exists('tests/')" description: "Check if tests directory exists" security: security_scanning: enabled: true tools: ["cargo-audit", "snyk"] schedule: "daily" vulnerability_thresholds: critical: 0 high: 0 medium: 5 low: 10 access_control: enabled: true access_levels: - name: "admin" permissions: ["read", "write", "delete", "admin"] description: "Full administrative access" - name: "developer" permissions: ["read", "write"] description: "Developer access" - name: "reviewer" permissions: ["read", "review"] description: "Reviewer access" policies: - name: "main-branch-protection" rules: - name: "admin-only" pattern: "main" permissions: ["admin"] effect: "allow" secrets_management: enabled: true provider: "vault" config: vault_url: "https://vault.example.com" auth_method: "token" rotation: enabled: true interval_days: 90 notification: true compliance: framework: "SOC2" rules: - name: "encryption-at-rest" description: "All data must be encrypted at rest" check: "encryption_enabled" severity: "critical" - name: "access-control" description: "Access control must be enabled" check: "access_control_enabled" severity: "high" reporting: enabled: true format: "json" destination: "compliance-reports" schedule: "monthly" integrations: cicd: enabled: true provider: "github-actions" config: workflow_file: ".github/workflows/ci.yml" pipeline: stages: - name: "validate" commands: ["cargo check", "cargo clippy"] dependencies: [] timeout_minutes: 10 - name: "test" commands: ["cargo test"] dependencies: ["validate"] timeout_minutes: 20 - name: "build" commands: ["cargo build --release"] dependencies: ["test"] timeout_minutes: 30 triggers: ["push", "pull_request"] artifacts: ["target/release/rhema"] issue_tracking: enabled: true provider: "github" config: repository: "user/my-project" templates: bug: "templates/bug.md" feature: "templates/feature.md" communication: enabled: true channels: - name: "general" channel_type: "slack" config: webhook_url: "https://hooks.slack.com/..." - name: "alerts" channel_type: "email" config: smtp_server: "smtp.gmail.com" smtp_port: 587 notifications: events: ["deployment", "security_alert", "build_failure"] recipients: ["team@example.com"] format: "html" monitoring: enabled: true provider: "datadog" config: api_key: "your-api-key" app_key: "your-app-key" metrics: ["cpu", "memory", "response_time", "error_rate"] custom: {} audit_log: changes: [] created_at: "2024-01-01T00:00:00Z" updated_at: "2024-01-01T00:00:00Z" health: status: "healthy" issues: [] recommendations: [] last_check: "2024-01-01T00:00:00Z" stats: total_configs: 1 global_configs: 0 repository_configs: 1 scope_configs: 0 encrypted_configs: 0 backup_count: 0 last_backup: null validation_errors: 0 migration_pending: 0 updated_at: "2024-01-01T00:00:00Z"

Security Features

Encryption

The configuration system supports encryption for sensitive configuration data:

# Enable encryption rhema config set global security.encryption.enabled true # Set encryption algorithm rhema config set global security.encryption.algorithm "AES-256-GCM" # Set key file rhema config set global security.encryption.key_file "~/.rhema/keys/master.key"

Access Control

Role-based access control for configuration management:

# Enable RBAC rhema config set global security.authorization.rbac_enabled true # Set default role rhema config set global security.authorization.default_role "user" # Set admin role rhema config set global security.authorization.admin_role "admin"

Audit Logging

Comprehensive audit logging for configuration changes:

# Enable audit logging rhema config set global security.audit.enabled true # Set audit log level rhema config set global security.audit.log_level "info" # Set audit log file rhema config set global security.audit.log_file "~/.rhema/logs/audit.log"

Best Practices

Configuration Organization

  1. Use Environment-Specific Settings: Configure different settings for development, testing, staging, and production environments.

  2. Secure Sensitive Data: Use encryption for sensitive configuration data and avoid storing secrets in plain text.

  3. Version Control: Keep configuration files in version control for tracking changes and collaboration.

  4. Validation: Always validate configuration changes before applying them.

  5. Backup: Regularly backup configuration files and test restore procedures.

  6. Documentation: Document configuration options and their purposes.

  7. Incremental Changes: Make small, incremental changes to configuration rather than large changes.

  8. Testing: Test configuration changes in a safe environment before applying to production.

Security Best Practices

  1. Encrypt Sensitive Data: Use encryption for API keys, passwords, and other sensitive information.

  2. Use Environment Variables: Store sensitive data in environment variables when possible.

  3. Implement Access Control: Use role-based access control to limit who can modify configuration.

  4. Audit Changes: Enable audit logging to track all configuration changes.

  5. Regular Reviews: Regularly review configuration for security issues.

  6. Principle of Least Privilege: Grant only the minimum necessary permissions.

  7. Secure Storage: Store configuration files securely with appropriate file permissions.

  8. Backup Security: Ensure backup files are also secured and encrypted.

Performance Best Practices

  1. Cache Configuration: Enable caching for frequently accessed configuration data.

  2. Optimize File Size: Keep configuration files concise and well-organized.

  3. Lazy Loading: Load configuration data only when needed.

  4. Validation Efficiency: Use efficient validation rules and avoid expensive operations.

  5. Monitoring: Monitor configuration system performance and usage.

Troubleshooting

Common Issues

  1. Configuration Not Found: Ensure configuration files exist in the expected locations.

  2. Permission Denied: Check file permissions and user access rights.

  3. Validation Errors: Review validation rules and fix configuration issues.

  4. Encryption Errors: Verify encryption keys and configuration.

  5. Import/Export Issues: Check file formats and ensure compatibility.

Debugging

# Enable debug mode rhema config set global application.settings.debug_mode true # Enable verbose logging rhema config set global application.settings.verbose_logging true # Check configuration health rhema config health all # Validate configuration rhema config validate all # Show configuration statistics rhema config stats all

Recovery

# Restore from backup rhema config restore global --backup-file backup-2024-01-01.json # Reset to defaults rhema config reset global --confirm # Migrate configuration rhema config migrate all

API Reference

Configuration Manager

The ConfigManager provides the main interface for configuration management:

pub struct ConfigManager { global_config: GlobalConfig, repository_configs: HashMap<PathBuf, RepositoryConfig>, scope_configs: HashMap<PathBuf, ScopeConfig>, security_manager: SecurityManager, tools_manager: ToolsManager, validation_manager: ValidationManager, migration_manager: MigrationManager, backup_manager: BackupManager, }

Key Methods

  • new() - Create a new configuration manager

  • global_config() - Get global configuration

  • load_repository_config() - Load repository configuration

  • validate_all() - Validate all configurations

  • backup_all() - Backup all configurations

  • migrate_all() - Migrate all configurations

Configuration Traits

All configuration types implement the Config trait:

pub trait Config: Serialize + DeserializeOwned + Validate { fn version(&self) -> &str; fn validate_config(&self) -> RhemaResult<()>; fn load_from_file(path: &Path) -> RhemaResult<Self>; fn save_to_file(&self, path: &Path) -> RhemaResult<()>; fn schema() -> serde_json::Value; fn documentation() -> &'static str; }

Future Enhancements

Planned Features

  1. Configuration Templates: Pre-built configuration templates for common use cases.

  2. Configuration Wizards: Interactive wizards for setting up configuration.

  3. Configuration Synchronization: Synchronize configuration across multiple environments.

  4. Configuration Analytics: Advanced analytics and insights for configuration usage.

  5. Configuration Governance: Enhanced governance and compliance features.

  6. Configuration Testing: Automated testing of configuration changes.

  7. Configuration Rollback: Advanced rollback capabilities for configuration changes.

  8. Configuration Monitoring: Real-time monitoring of configuration health and performance.

Integration Roadmap

  1. Cloud Providers: Enhanced integration with AWS, Azure, and GCP.

  2. CI/CD Platforms: Better integration with GitHub Actions, GitLab CI, and Jenkins.

  3. Monitoring Tools: Integration with Prometheus, Grafana, and other monitoring tools.

  4. Security Tools: Integration with Vault, AWS Secrets Manager, and other security tools.

  5. IDE Extensions: Enhanced IDE integration for configuration management.

Contributing

To contribute to the configuration management system:

  1. Follow the Code Style: Adhere to the project’s coding standards and conventions.

  2. Add Tests: Include comprehensive tests for new features and changes.

  3. Update Documentation: Keep documentation up to date with changes.

  4. Security Review: Ensure security implications are considered for all changes.

  5. Performance Testing: Test performance impact of configuration changes.

  6. Backward Compatibility: Maintain backward compatibility when possible.

  7. Configuration Validation: Ensure new configuration options are properly validated.

  8. Error Handling: Implement proper error handling and user-friendly error messages.

Support

For support with the configuration management system:

  1. Documentation: Check this documentation and other project documentation.

  2. Issues: Report issues on the project’s issue tracker.

  3. Discussions: Participate in project discussions and forums.

  4. Examples: Review example configurations and use cases.

  5. Community: Engage with the community for help and best practices.

Last updated on