/
DR-000044 - Environment Variables

DR-000044 - Environment Variables

Submitted Date

2025-11-19

Approved Date

2025-11-24

Status

ACCEPTED

Impact

MEDIUM

 

Overrides/Supersedes 

Overrides initial module evaluation criteria at tech-council/MODULE_ACCEPTANCE_CRITERIA.MD at f7cc4afee3dde7fc9833d6134c213a2f5344022d · folio-org/tech-council

RFC 

NA

Stakeholders

@mention individual(s) who has vested interest in the DR. This helps us to identify who needs to be aware of the decision

Contributors

FOLIO Community members across many dedicated discussions.

Approvers

List TC members voted to approve the change

Background/Context

FOLIO modules currently use inconsistent environment variable naming conventions and documentation practices, creating several
operational challenges:

  1. Inconsistent Naming: Different modules use varying prefixes for the same infrastructure (e.g., AWS_ vs S3_ for cloud storage,
    inconsistent database variable names)

  2. Poor Documentation: Environment variables are often undocumented or incompletely documented, making deployment difficult

  3. Operational Burden: System administrators must learn module-specific conventions for each deployment

  4. Configuration Errors: Lack of clear required vs. optional variable classification leads to misconfiguration and runtime failures

This decision establishes comprehensive standards to provide a consistent operational experience across all FOLIO modules while
supporting gradual migration of existing modules.

Assumptions

  1. Dual Support Feasibility: Existing modules can support both old and new environment variable names simultaneously without significant technical burden

  2. DevOps Automation: The DevOps team will create automated tooling to generate human-readable ENV_VARS.md files from ModuleDescriptor definitions, reducing manual documentation effort

  3. ModuleDescriptor schema will be updated by OKAPI dev team to include new properties.

Constraints

  1. Backward Compatibility: Cannot break existing deployments - must maintain support for legacy variable names indefinitely or for an extended transition period

  2. Third-Party Libraries: Framework-specific behavior may override standardized handling for third-party library configuration

  3. Deployment Diversity: Must work across various deployment models (Docker, Kubernetes, traditional VMs)

Rationale

This policy addresses critical operational and maintenance challenges in FOLIO deployments by establishing the ModuleDescriptor as the authoritative source of truth for environment variable configuration, enabling automated tooling and deployment pipelines to programmatically validate and manage module configuration. By requiring comprehensive documentation fields (name, default value, required flag, and description) in the ModuleDescriptor, operators receive complete information needed for successful deployments without consulting multiple sources or reverse-engineering module behavior.

The clear distinction between required and optional variables prevents ambiguity about which variables must be set for module operation, directly improving error messages and troubleshooting workflows. When required variables are missing, the fail-fast startup behavior prevents silent misconfigurations from reaching production environments, shifting configuration validation left in the deployment pipeline where issues are cheaper and faster to resolve. This approach contrasts with modules that start successfully but fail during runtime with cryptic errors due to missing configuration.

The dual-support migration strategy maintains backward compatibility with existing deployments while providing a clear path forward. By supporting both legacy and standardized variable names simultaneously, modules allow gradual migration without requiring coordinated "big bang" changes across all environments. Operators can migrate individual modules or environments at their own pace, significantly reducing the risk of breaking production systems during the transition period.

Decision

Adopt the Environment Variable policy at https://folio-org.atlassian.net/wiki/x/NYCgTg and augment module evaluation criteria to include the policy's finer points.

Implications

  • Pros

    • Consistent Operational Experience: System administrators work with uniform variable names across all FOLIO modules

    • Improved Documentation: Complete, standardized documentation reduces deployment errors and troubleshooting time

    • Better Error Messages: Fail-fast behavior with clear messages enables faster problem resolution

    • Vendor Neutrality: S3_ prefix supports multiple cloud providers while maintaining S3 API compatibility

    • Gradual Migration: Dual support strategy minimizes disruption to existing deployments

    • Quality Gate: Integration into module acceptance criteria ensures all new modules comply

  • Cons

    • Migration Effort: Existing modules require code changes to support dual variable naming

    • Dual Support Overhead: Maintaining both old and new variable names adds code complexity during transition

    • Testing Complexity: Must test both old and new variable paths during transition period

    • No Hard Timeline: Lack of cutoff date means legacy variables may persist indefinitely in some modules

Other Related Resources