Skip to content

environment-variable-prefix.md

Latest commit

 

History

History
110 lines (67 loc) · 3.86 KB

environment-variable-prefix.md

File metadata and controls

110 lines (67 loc) · 3.86 KB

Decision: Environment Variable Prefix Convention

Status

Accepted

Date

2025-11-03

Context

The Torrust Tracker Deployer application needs a consistent naming convention for environment variables. This is important for:

  • Project identification: Making it clear which project's variables are being used in shared environments
  • Namespace collision avoidance: Preventing conflicts with system variables or other applications
  • Ecosystem consistency: Aligning with other Torrust projects for a unified developer experience
  • Discoverability: Making it easy to find all project-related environment variables (e.g., using env | grep TORRUST_TD_)

Without a standardized prefix, environment variables could conflict with other applications or be difficult to identify as belonging to the Torrust Tracker Deployer project.

Decision

All environment variables used by the Torrust Tracker Deployer application will use the prefix TORRUST_TD_.

Prefix breakdown:

  • TORRUST_ - Identifies variables belonging to the Torrust ecosystem
  • TD_ - Stands for "Tracker Deployer", identifying this specific project within the ecosystem

Example:

TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER=true

This is currently the only environment variable used by the application. Future environment variables will follow this same prefix convention.

Consequences

Positive

  • Clear project identification: Anyone seeing these variables immediately knows they belong to Torrust Tracker Deployer
  • Ecosystem consistency: All Torrust projects share the TORRUST_ prefix, creating a unified namespace
  • No namespace collisions: The specific TORRUST_TD_ prefix prevents conflicts with system variables or other applications
  • Easy filtering: Variables can be easily listed with env | grep TORRUST_TD_ or similar commands
  • Reasonable length: The prefix is concise enough to avoid excessive verbosity while remaining descriptive

Negative

  • Slightly verbose: The prefix adds 11 characters to every environment variable name
  • Potential for confusion: New contributors might initially be unclear what "TD" stands for (mitigated by documentation)
  • Migration effort: Existing code using different variable names will need to be updated

Alternatives Considered

Option 1: TORRUST_TRACKER_DEPLOYER_ (Full Project Name)

Pros:

  • Maximally explicit - no ambiguity about what "TD" means
  • Self-documenting

Cons:

  • Too verbose: 25 characters for the prefix alone
  • Results in very long variable names (e.g., TORRUST_TRACKER_DEPLOYER_CONFIG_PATH)
  • Cumbersome to type and read

Decision: Rejected due to excessive length

Option 2: TRACKER_DEPLOYER_ (No Ecosystem Prefix)

Pros:

  • Shorter than full prefix
  • Still identifies the project

Cons:

  • Lacks ecosystem consistency: Doesn't align with other Torrust projects
  • Less distinctive: "TRACKER_DEPLOYER" is more generic than "TORRUST_TD"
  • Harder to identify: Not immediately clear it's part of the Torrust ecosystem

Decision: Rejected due to lack of ecosystem alignment

Option 3: TT_DEPLOYER_ (Abbreviated Both Parts)

Pros:

  • Very short (11 characters)
  • Still somewhat identifiable

Cons:

  • Ambiguous abbreviation: "TT" could mean many things (not obviously "Torrust Tracker")
  • Inconsistent with ecosystem: Other Torrust projects may not use similar abbreviations
  • Less discoverable: Harder to guess or search for

Decision: Rejected due to ambiguity

Related Decisions

  • None yet - this is the first ADR establishing environment variable conventions

References