2025-10-29 Environment Variable Management II

1 min

Scribe

@Wayne Schneider is next, followed by @Florian Gleixner

Wayne should scribe next week

Reminder:  Please copy/paste the Zoom chat into the notes.  If you miss it, this is saved along with the meeting recording, but having it here has benefits.

Module Evaluation Criteria

ALL

Proposed Additional Module Evaluation Criteria:

• [ ] All environment variables follow naming convention (DB_, KAFKA_, S3_/AWS_ per standard)

• [ ] ModuleDescriptor includes description for each variable

• [ ] README.md includes environment variable table with: Name | Default | Required | Description

  • @Olamide Kolawole this could be generated automatically

• [ ] Required vs optional variables clearly marked

• [ ] Feature flags use consistent naming (e.g., *_ENABLED suffix)

• [ ] Module startup validates required variables and fails fast with clear errors

@Ingolf Kuss There was a sysops meeting about environment variables, where some recommendations were made. This should be included

Review https://folio-org.atlassian.net/wiki/x/NYCgTg

ALL

• System User variables:

  • @Olamide Kolawole all OK with SYSTEM_USER_USERNAME

  • @Wayne Schneider do we have to provide all three variables if we develop a module, that needs a system user?

  • @Olamide Kolawole We should add this to the document

• @Wayne Schneider There can be additional variables not mentioned in the table too

• Discussion about ENV: Only for Kafka? Rename to KAFKA_ENV? Seems to be used somewhere else too (Elasticsearch)

• @Ingolf Kuss Variables with dots should not be used

• @Julian Ladisch Spring converts variables automatically, so only the uppercase with underscore should be used and documented

• @Olamide Kolawole Many modules use variables with dots. Shall we disallow them?

• @Wayne Schneider This is probably only a documentation issue, because most are automatically converted from uppercase underscore.

• All variables should be uppercase-underscore

• @Florian Gleixner this is only relevant on startup of the container. If the program needs other variables, the start script has to convert them

• @Julian Ladisch Keycloak variables are defined upstream and should not be altered

• @Ingolf Kuss should we change how ENV is used? Shall we separate it to KAFKA_ENV and ELASTIC_ENV

• @Wayne Schneider and @Florian Gleixner Yes, this should be addressed, but not in this discussion. We need a separate discussion and decision with a plan how to migrate during a release upgrade.

• @Ingolf Kuss Why ELASTICSEARCH_* and not ES_*?

• @Olamide Kolawole We could change it, but is it worth?

• @Wayne Schneider in the past, changes to variables were made because of the change of the underlying library. We should get independent from that. But is it worth the trouble?

• @Olamide Kolawole Then we keep ELASTICSEARCH_* for now

• Documentation Requirements: ModuleDescriptor should contain environment variables:

  • @Julian Ladisch and @Wayne Schneider this is not possible, because the MD is used to build reference environments. Adding all environment variables could break building these.

  • @Florian Gleixner MD schema could be extended for additional env

  • @Olamide Kolawole would not extend the schema, but write them in the Readme

  • @Shelley Doljack would also not extend the MD schema

  • @Wayne Schneider changing the MD schema is probably is not a breaking change when we add a property. Env in deployment descriptors are not used nowadays.

  • @Wayne Schneider will try to find a name for the new property

NA

Zoom Chat

2025-10-29 16:08:36 Von Wayne Schneider Bis Alle:
Apologies, I know I was supposed to scribe, I will scribe the next meeting. I was held up and unable to join on time.

2025-10-29 16:12:23 Von Ingolf Kuss Bis Alle:
Eureka variables naming convention discussion in SysOps SIG, notes : https://folio-org.atlassian.net/wiki/spaces/SYSOPS/pages/1034322832

2025-10-29 16:14:27 Von Ingolf Kuss Bis Alle:
variables with dots should be generally disallowed, like okapi.url , tenant.url, kong.url , am.url

2025-10-29 16:25:01 Von Wayne Schneider Bis Alle:
Olamide has dropped

2025-10-29 16:25:03 Von Christie Thomas (she/her) Bis Alle:
Olamide posted in the slack channel that he is having networking issues. I see that he has dropped from the call.

2025-10-29 16:26:02 Von Julian Ladisch Bis Alle:
https://folio-org.atlassian.net/wiki/spaces/TC/pages/1319141429

2025-10-29 16:26:59 Von Julian Ladisch Bis Alle:
A period/dot in an environment variable is not POSIX compliant:
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html
Environment variable names used by the utilities in the Shell and Utilities volume of POSIX.1-2017 consist solely of uppercase letters, digits, and the <underscore> ( '_' ) from the characters defined in Portable Character Set and do not begin with a digit.
Some shells strip each period/dot for security reasons, including the Almquist shell that is the default non-interactive shell in Alpine, Ubuntu, Debian, and other distributions because of efficiency: speed of execution, disk space, RAM, CPU, and security.
For security the Almquist shell is used to run Java modules.

2025-10-29 16:36:48 Von Wayne Schneider Bis Alle:
LOL that was maybe a thought, not a proposal. If it was taken as a proposal I retract it