BUCKYVERSE

Date: 2025-02-25

Status

Accepted

Context

Our ebook conversion system needs to operate in different environments (development, test, production) with environment-specific settings. Currently, our configuration system uses a single configuration file, which leads to several issues:

  1. Development vs. Production Settings: Different environments require different settings (e.g., paths, timeouts, log levels)
  2. Testing Challenges: Tests need isolated configuration to avoid affecting development settings
  3. Deployment Complexity: Deployment requires manual configuration changes
  4. Security Concerns: Sensitive production settings shouldn't be in development configuration
  5. Hardcoded Values: Many environment-specific values are hardcoded rather than configured

Our existing configuration system loads from a single YAML file and performs basic validation, but doesn't account for different environments.

Decision

We will implement an environment-specific configuration system with the following components:

  1. Environment Detection:

    • Create a BookProcessing::Environment class to detect and manage the current environment
    • Support explicit environment setting via the BOOK_ENV environment variable
    • Define standard environments: development, test, and production
    • Provide environment checking methods (development?, test?, production?)

  2. Layered Configuration:

    • Base configuration file (config/base.yml) for shared settings
    • Environment-specific configuration files (config/{environment}.yml)
    • Environment variable overrides for runtime configuration

  3. Configuration Loading Strategy:

    • Load base configuration first
    • Overlay environment-specific configuration
    • Apply environment variable overrides
    • Use deep merging for nested configuration

  4. Environment-Specific Validation:

    • Apply different validation rules based on the environment
    • Stricter validation for production
    • More permissive validation for development
    • Special handling for test environment

  5. Default Values:

    • Provide sensible defaults for each environment
    • Document required vs. optional configuration

Implementation

The implementation includes:

  1. A new BookProcessing::Environment class for environment detection and management
  2. Enhanced BookProcessing::Configuration class with environment-specific loading
  3. Environment-specific configuration files for development, test, and production
  4. Environment variable override support for runtime configuration
  5. Environment-specific validation rules

Consequences

Positive

  1. Environment Isolation: Each environment has its own configuration
  2. Simplified Deployment: No need to manually change configuration during deployment
  3. Enhanced Testing: Tests can run with isolated configuration
  4. Improved Security: Sensitive settings can be kept separate
  5. Runtime Flexibility: Environment variables allow runtime configuration
  6. Reduced Hardcoding: More values can be moved to configuration
  7. Clearer Defaults: Each environment has appropriate defaults

Negative

  1. Increased Complexity: Multiple configuration files to maintain
  2. Potential Duplication: Some settings may be duplicated across environments
  3. Configuration Drift: Environments may become inconsistent over time
  4. Learning Curve: Developers need to understand the layered configuration system

Mitigation Strategies

  1. Documentation: Clear documentation of the configuration system
  2. Configuration Templates: Provide templates for each environment
  3. Validation Tools: Create tools to validate configuration across environments
  4. Configuration Review: Regular review of configuration files for consistency
  5. Default Fallbacks: Ensure sensible defaults when configuration is missing

References