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

New Issue

3wordchant · 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.
b5d40aa428/compose.yml (L77)
- 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.

Sign in to join this conversation.

No Milestone

No project

No Assignees

3 Participants

Notifications

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: coop-cloud/organising#359