From 1618faa420aacf6e0a795b00787be448099ee989 Mon Sep 17 00:00:00 2001
From: lambdabundesverband <it@lambda-online.de>
Date: Wed, 4 Jun 2025 16:40:33 +0000
Subject: [PATCH] docs/maintainers/handbook.md aktualisiert

Thats how I until now understood process of adding an env var. Thought it might help other's who are new. I am very open to suggestions, other best practices, corrected typos...
---
 docs/maintainers/handbook.md | 37 ++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md
index f10c6b4..807b865 100644
--- a/docs/maintainers/handbook.md
+++ b/docs/maintainers/handbook.md
@@ -124,6 +124,43 @@ You can also access it in your configs using the following syntax:
 {{ env "FOO" }}
 ```
 
+### Example: Adding environment variables to existing recipe
+Here is a four step example how to add a new environment variable to a recipe without breaking existing deployments. 
+
+1. add env-var to the `compose.yml` in section `environment`:
+   ```yaml
+       environment:
+         # ... existing envs
+         - REQUIRE_AUTH_FOR_PROFILE_REQUESTS=${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}
+         # ... other existing envs
+   ```
+
+   With `${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}` you set a default value (`false`), ensuring not to break existing deployments. 
+   If you're sure that it won't cause problems, if operators of existing deployments don't set the variable, you could also just put:
+   ```yaml
+       environment:
+         # ... existing envs
+         - REQUIRE_AUTH_FOR_PROFILE_REQUESTS
+         # ... other exisitng envs
+   ```
+
+2. add env-var to the `.env.sample`
+   ```yaml
+   #REQUIRE_AUTH_FOR_PROFILE_REQUESTS=true
+   ```
+
+3. now you can use the environment-variable in your `.tmpl` files, e.g. add to `homserver.yaml.tmpl`
+   ```yaml
+   require_auth_for_profile_requests: {{ env "REQUIRE_AUTH_FOR_PROFILE_REQUESTS" }}
+   ```
+   
+4. increase number of YAML-version in `abra.sh` (e.g. from `v30` to `v31`), only then it will be deployed. 
+   ```yaml
+   export HOMESERVER_YAML_VERSION=v31
+   ```
+
+   Note: If during development and testing you have to increase it several times, you can just "flatten" it in the end. Only make sure that you `undeploy`/`deploy` your existing instance.
+
 ### Global environment variables
 
 - `TYPE`: specifies the recipe name