Establish a convention for optional/default settings in .env files #359
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: toolshed/organising#359
Loading…
x
Reference in New Issue
Block a user
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Tales from coop-cloud/plausible!1:
If a recipe has an optional setting called
DISABLE_AUTH, with an implicit default offalse, should the contents of the recipe's.env.samplefile be:DISABLE_AUTH=false(to make the default explicit)#DISABLE_AUTH=false(to make the default explicit, and also show that it's optional)#DISABLE_AUTH=true(to show the likely change someone would want to make by settingDISABLE_AUTH)#DISABLE_AUTH=(to make the actual default value, where the variable is completely un-set, explicit)All sound fine to me. Some people are also doing
#FOO=and leaving it empty completely. As recipe maintenance becomes more widespread / decentered, I'd imagine several practices will emerge.I agree that it is nice to have as little possible to configure in order to get a working deployment up-and-running. Maybe this is a documentation thing in general? Each env var should have some explanation? I'm not sure.
Oh yeah good call, adding to the issue description to round out the options.
Yeah, I feel an "advice for
.env.samplefiles section of the docs emerging 🧙Starting with "Files should include sensible defaults, as far as possible -- operators should ideally not need to change settings to get a basic instance of the recipe running"..
..and continuing with "Every option should include some explanation of what it does, ideally linking to upstream documentation"
I would favor this way.
Makes sense to me!
I added
c82437da8f👍Setting different default values for the recipe could be done in the compose.yml and the .env variable can still be commented.
- FPM_START_SERVERS=${FPM_START_SERVERS:-32}Attempted recap of some conversation in coop-cloud/gitea!36, and Matrix.
We should also have some advice for:
1. When we want to set a different default in a recipe than upstream does
e.g.
GITEA_DEFAULT_USER_VISIBILITY=limited, where the default ispublicMy suggestion here would be to add a text comment in
.env.sampleexplaining what the upstream default is, and why we recommend a different one.2. When we add a new mandatory option to a recipe
e.g.
NGINX_ACCESS_LOG_LOCATION, where this is required for a container to launchSuggestion is, for these variables only (i.e. not for ones included in
.env.samplefrom the start), to use${NGINX_ACCESS_LOG_LOCATION:-foobar}(compose.yml) or{{ or (env "NGINX_ACCESS_LOG_LOCATION") "foobar" }}(golang template, e.g. config) to provide a fallback value – thus avoiding the need for a new Major recipe release just for the new setting.Optionally, these defaults could be removed after some sensible deprecation period, or with the next major recipe release.
I would additionally recommend to add a release note comment for every new different default value.