Establish a convention for optional/default settings in .env files #359

New Issue

2022-11-11T19:30:49Z

3wordchant commented

2022-11-11 19:30:49 +00:00

If a recipe has an optional setting called DISABLE_AUTH, with an implicit default of false, should the contents of the recipe's .env.sample file 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 setting DISABLE_AUTH)
#DISABLE_AUTH= (to make the actual default value, where the variable is completely un-set, explicit)

Tales from [coop-cloud/plausible!1](https://git.coopcloud.tech/coop-cloud/plausible/pulls/1/files): If a recipe has an optional setting called `DISABLE_AUTH`, with an implicit default of `false`, should the contents of the recipe's `.env.sample` file 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 setting `DISABLE_AUTH`) - `#DISABLE_AUTH=` (to make the actual default value, where the variable is completely un-set, explicit)

3wordchant added the documentation label 2022-11-11 19:30:49 +00:00

3wordchant referenced this issue from coop-cloud/plausible

2022-11-11 19:31:24 +00:00

Adding two new variables to disable registration and login #1

decentral1se commented

2022-11-12 16:49:07 +00:00

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.

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.

3wordchant commented

2022-11-13 00:09:24 +00:00

All sound fine to me. Some people are also doing #FOO=

Oh yeah good call, adding to the issue description to round out the options.

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?

Yeah, I feel an "advice for .env.sample files 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"..

Each env var should have some explanation? I'm not sure.

..and continuing with "Every option should include some explanation of what it does, ideally linking to upstream documentation"

> All sound fine to me. Some people are also doing `#FOO=` Oh yeah good call, adding to the issue description to round out the options. > 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? Yeah, I feel an "advice for `.env.sample` files 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".. > Each env var should have some explanation? I'm not sure. ..and continuing with "Every option should include some explanation of what it does, ideally linking to upstream documentation"

❤️ 1

moritz commented

2022-12-22 15:28:26 +00:00

#DISABLE_AUTH=true (to show the likely change someone would want to make by setting DISABLE_AUTH)

I would favor this way.

To change the default value, it is only necessary to uncomment it
Many variables are unset per default, this way you already know how to define the variable.

> - `#DISABLE_AUTH=true` (to show the likely change someone would want to make by setting `DISABLE_AUTH`) I would favor this way. 1. To change the default value, it is only necessary to uncomment it 2. Many variables are unset per default, this way you already know how to define the variable.

👍 1

3wordchant commented

2022-12-22 15:57:03 +00:00

Makes sense to me!

decentral1se referenced this issue

2023-04-14 17:04:53 +00:00

Checking for env changes #446

decentral1se referenced this issue

2023-10-05 22:41:10 +00:00

Checking for env changes #446

decentral1se referenced this issue from a commit

2023-10-06 09:12:42 +00:00

refactor: more warnings for default env vars

decentral1se commented

2023-10-06 09:13:18 +00:00

I added c82437da8f 👍

I added https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/commit/c82437da8fcc5182d55158cea639395830904737 👍

moritz commented

2024-04-17 07:59:29 +00:00

Setting different default values for the recipe could be done in the compose.yml and the .env variable can still be commented.

		nextcloud/compose.yml
		Line 77 in b5d40aa428
	
				      - FPM_START_SERVERS=${FPM_START_SERVERS:-32}

- FPM_START_SERVERS=${FPM_START_SERVERS:-32}

Setting different default values for the recipe could be done in the compose.yml and the .env variable can still be commented. https://git.coopcloud.tech/coop-cloud/nextcloud/src/commit/b5d40aa428f324d32e0d8e8c3b5204f17efb1222/compose.yml#L77 `- FPM_START_SERVERS=${FPM_START_SERVERS:-32}`

👍 1

3wordchant referenced this issue from coop-cloud/gitea

2024-04-21 23:29:09 +00:00

Adding more variable configs #36

3wordchant commented

2024-04-21 23:36:49 +00:00

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 is public

My suggestion here would be to add a text comment in .env.sample explaining 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 launch

Suggestion is, for these variables only (i.e. not for ones included in .env.sample from 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.

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 is `public` My suggestion here would be to add a text comment in `.env.sample` explaining 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 launch](https://git.coopcloud.tech/coop-cloud/matrix-synapse/src/branch/main/nginx.conf.tmpl#L11) Suggestion is, for these variables only (i.e. not for ones included in `.env.sample` from 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.

👍 1

moritz commented

2024-04-23 11:54:34 +00:00

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 is public

My suggestion here would be to add a text comment in .env.sample explaining what the upstream default is, and why we recommend a different one.

I would additionally recommend to add a release note comment for every new different default value.

> ### 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 is `public` > > My suggestion here would be to add a text comment in `.env.sample` explaining what the upstream default is, and why we recommend a different one. I would additionally recommend to add a release note comment for every new different default value.

👍 1

decentral1se referenced this issue from coop-cloud/gitea

2025-01-07 16:48:48 +00:00

feat: support other smtp protocols #39

decentral1se added this to the (deleted) project 2025-04-20 06:04:31 +00:00

decentral1se commented

2026-03-21 16:34:39 +00:00

OK, I think there is enough of a precedent for the backwards compat approach to start recommending it officially. I have done that in https://docs.coopcloud.tech/maintainers/upgrade/. Feedback welcome.

There are still some additional nuances in #359 (comment) which I don't believe are documented. I guess we can leave this open still. Perhaps creating a table with a bit of systematic overview of when/where/why in relation to environment variable updates, would be helpful for others diving in.

OK, I think there is enough of a precedent for the backwards compat approach to start recommending it officially. I have done that in https://docs.coopcloud.tech/maintainers/upgrade/. Feedback welcome. There are still some additional nuances in https://git.coopcloud.tech/toolshed/organising/issues/359#issuecomment-20480 which I don't believe are documented. I guess we can leave this open still. Perhaps creating a table with a bit of systematic overview of when/where/why in relation to environment variable updates, would be helpful for others diving in.

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: toolshed/organising#359