sidenote to clarify how local abra works

- use curl for consistency
- copied the warning from the install script (i.e., do not use for prod
  envs)

docs/abra/hack.md

@@ -359,8 +359,35 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 - Push the new tag (e.g. `git push && git push --tags`)
 - Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
 - Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
+- Clean up the changelog on the releases page so it includes most relevant
+  changes. See below for the announcement text that needs to be inserted above
+  the generated changelog. You can use something like `git shortlog -e -s -n
+  0.11.0-beta..HEAD` to get the list of authors.
+- Make sure there is a migration guide written in the docs (if necessary)
 - Check the release worked, (e.g. `abra upgrade; abra -v`)
-- Share the announcement:
+- Share the announcement on our General chat and fedi account:
+
+#### Release notes text
+
+```
+## Changelog   
+
+> 🎺🎺🎺 [`0.XX.x-beta` 👉 `0.XX.0-beta` **migration guide**](XXX) 🎺🎺🎺
+
+`abra` update `HOWTO` documentation is [here](https://docs.coopcloud.tech/abra/upgrade/).
+
+The project with all changes and discussions is [here](XXX).
+
+A huge thanks to all our `abra` hackers for this release 💖
+
+```
+...
+```
+
+$CHANGELOG
+```
+
+#### General announcement text
 
 ```
 📢📢📢 abra v0.XX  is finally here 📢📢📢
@@ -379,6 +406,8 @@ https://docs.coopcloud.tech/abra/upgrade/#XXx-beta-0XXx-beta
 A huge thanks to everyone who helped get this release done ❤️‍🔥
 
 Happy Hacking 🫂
+
+-- $handle
 ```
 
 ## Fork maintenance

docs/abra/upgrade.md

@@ -53,6 +53,12 @@ And test things work.
 
 > General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)
 
+### `0.11.x-beta` -> `0.12.x-beta`
+
+* `kadabra` has been archived and is no longer published alongside `abra`
+  releases. See [`#699`](https://git.coopcloud.tech/toolshed/abra/issues/699)
+  for more.
+
 ### `0.10.x-beta` -> `0.11.x-beta`
 
 * Timeouts are no longer used unless specifically set in the app `.env` file,

docs/federation/resolutions/passed/034.md

@@ -1,5 +1,5 @@
 ---
-title: Resolution 034
+title: "Resolution 034: Extra budget for Escuela Común recipes"
 ---
 
 - Topic: Budget 015: Extra budget for recipes needed by Escuela Común

docs/maintainers/handbook.md

@@ -53,6 +53,12 @@ I.e. `compose.smtp.yml`. These are used to provide non-essential functionality s
 
 If you look at a `compose.yml` file and see a `configs` section, that means this compose file is putting files in the container. This might be used for changing default (vendor) configuration, such as this [fpm-tune.ini file](https://git.coopcloud.tech/coop-cloud/nextcloud/src/commit/28425b6138603067021757de28c639ad464e9cf8/fpm-tune.ini) used to adjust `php-fpm.` See [this handbook entry](/maintainers/handbook/#manage-configs) for more.
 
+### Special environment variables
+
+#### STACK_NAME
+
+Our deployment runtime expects a specific naming convention for Co-op Cloud apps when they are deployed on the server. This is a case of lowercasing/underscoring the domain name, e.g. "foo.coopcloud.tech" -> "foo_coopcloud_tech". This is for the most part an internal implementation detail. However, it is sometimes useful to expose this variable to template configurations when trying to connect apps together via runtime networking. See ["How do I reference serices in configs"](/maintainers/handbook/#how-do-i-reference-services-in-configs) for a practical example.
+
 ## Manage configs
 
 To add additional files into the container, you can use [Docker configs](https://docs.docker.com/engine/swarm/configs/). This usually involves the following:
@@ -323,18 +329,15 @@ Sometimes the containers don't even have Bash installed on them. You had better
 
 When referencing an `app` service in a config file, you should prefix with the `STACK_NAME` to avoid namespace conflicts (because all these containers sit on the traefik overlay network). You might want to do something like this `{{ env "STACK_NAME" }}_app` (using  the often obscure dark magic of the Golang templating language). You can find examples of this approach used in the [Peertube recipe](https://git.coopcloud.tech/coop-cloud/peertube/src/commit/d1b297c5a6a23a06bf97bb954104ddfd7f736568/nginx.conf.tmpl#L9).
 
-!!! warning "Here be timing dragons 🐉"
+!!! warning "Here be `STACK_NAME` dragons 🐉"
 
-    Due to how `STACK_NAME` as an environment variable is initialized within `abra`, it won't be available *early enough* for use within config templates (`*.tmpl`) unless you **use it as an environment variable for one of your compose services**.
+    `STACK_NAME` is a [**special environment variable**](/maintainers/handbook/#special-environment-variables) which `abra` generates for you and in the format the runtime deployment expects to see. If you want to expose this environment variable in your template configurations, you need to expose it explicitly to the `env: ...` stanza in your recipe compose configuration. An example follows below.
-    Ideally this is addressed in a newer version of `abra`, but for now, this workaround suffices ✅
 
-    E.g.
+    ```yaml
-    ```
       services:
         web:
           image: nginx:1.29.3
           environment:
-            - ...
             - STACK_NAME
     ```
 
@@ -590,7 +593,7 @@ SECRET_JWT_SECRET_VERSION=v1 # charset=default,special
 ```
 
 Options are:
-* `default`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L23)
+
 * `special`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L22C29-L22C43)
 * `safespecial`: [source](https://git.coopcloud.tech/toolshed/abra/src/commit/6abaf7a094df1a96599af2c4cbae1769821ad17c/pkg/secret/secret.go#L182)
 * `default,special`: mix of `default` and `special`

docs/operators/handbook.md

@@ -118,7 +118,7 @@ Then `$ABRA_DIR` will be automatically picked up as `$PWD`. This is useful when
 
 If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local computer.
 
-To install `abra` on the same server where you'll be hosting your apps, just follow [getting started guide](/operators/tutorial#deploy-your-first-app) as normal except for one difference. Instead of providing your SSH connection details when you run `abra server add ...`, just pass `--local`.
+To install `abra` on the same server where you'll be hosting your apps, just follow [getting started guide](/operators/tutorial#deploy-your-first-app) as normal except for one difference. Instead of providing your SSH connection details when you run `abra server add ...`, just pass `--local` and specify the domain during deployment.
 
 ```
 abra server add --local
@@ -320,6 +320,36 @@ If you need to run a command within a running container you can use `abra app ru
 
 If you need to run a command on a container that won't start (eg. the container is stuck in a restart loop) you can temporarily disable its default entrypoint by setting it in `compose.yml` to something like ['tail', '-f', '/dev/null'], then redeploy the stack (with `--force --chaos` so you don't need to commit), then [get into the now running container](#how-do-i-attach-to-a-running-container), do your business, and when done revert the compose.yml change and redeploy again.
 
+## How can I modify/override the `compose.yml-file`?
+
+If you need a customization of the `compose`-file, e.g., override a specific, hard coded value that is not present in the sample-env, add a custom volume, or add an environment variable that the image knows but which is not (yet) included in the `compose.yml` of the recipe, you can do so by using the `COMPOSE_FILE` environment variable ([more details in Docker docs](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_file)).
+
+For details about how the two compose files are merged, consult the official [Docker docs](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/).
+
+If it's not a special or edge case, perhaps consider modifying the original recipe / racing a feature request so everyone can benefit from your conceptual work?
+
+### Example 
+The upstream image of your `app` allows you to modify the SMTP port with an environment variable called `SMTP_PORT`, but the recipe's maintainers didn't include it in the compose file because they didn't have in mind anyone would need a non-standard port. So you can't simply add `SMTP_PORT` to your `yourapp.example.com.env`, because it won't find its way into the running container.
+
+For a quick fix, you could now create a file, e.g. `yourapp.example.com.compose.override.yml` (naming is up to you) with the content:
+
+```
+services:
+  app:
+    environment:
+      SMTP_PORT: 25
+```
+
+and add to your `yourapp.example.com.env`
+
+```
+COMPOSE_FILE="compose.yml:../../servers/<YOUR-SERVER>/yourapp.example.com.compose.override.yml
+```
+_Make sure you include the original `compose.yml` and place the `yourapp.domain.compose.override.yml` directly alongside of your `yourapp.example.com.env`, or change the (relative) path respectively._
+
+This will now add/overwrite the `SMTP_PORT` environment variable of the `app` container.
+
+`
 ## Can I run Co-op Cloud on ARM?
 
 `@Mayel`:

docs/operators/tutorial.md

@@ -36,7 +36,8 @@ Otherwise, here are the step required:
 ssh <server-domain>
 
 # docker install convenience script
-wget -O- https://get.docker.com | bash
+# not suitable for production environments - refer to the script header for alternatives
+curl https://get.docker.com | bash
 
 # check that docker was installed correctly
 sudo docker run hello-world
@@ -84,6 +85,10 @@ Where `116.203.211.204` can be replaced with the IP address of your server.
 
     You can use a tool like `dig` on the command-line to check if your server has the necessary DNS records set up. Something like `dig +short <domain>` should show the IP address of your server if things are working.
 
+??? question "Can I use DynDNS with a home server?"
+
+    Yes. If your DNS provider does not allow you to set a *. A-Record, you may still be able to use a *. CNAME-Record to your example.com domain.
+
 ### Install `abra`
 
 Now we can install [`abra`](/abra) locally on your machine and hook it up to your server. We support a script-based installation method ([script source](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer)):
@@ -183,9 +188,8 @@ You need to keep port `:80` and `:443` free on your server for web proxying to y
 
 ??? question "Do you support multiple web proxies?"
 
-   Yes, this is possible. See [this handbook
+    Yes, this is possible. See [this handbook entry](/operators/handbook/#proxying-apps-outside-of-co-op-cloud-with-traefik)
-   entry](/operators/handbook/#proxying-apps-outside-of-co-op-cloud-with-traefik)
+    for more. Be warned, this is a relatively advanced topic.
-   for more. Be warned, this is a relatively advanced topic.
 
 **1. To get started, you'll need to create a new app:**
 

mkdocs.yml

@@ -126,12 +126,12 @@ nav:
               - federation/resolutions/passed/032.md
               - federation/resolutions/passed/031.md
               - federation/resolutions/passed/033.md
+              - federation/resolutions/passed/034.md
           - "Stalled":
               - federation/resolutions/stalled/013.md
               - federation/resolutions/stalled/030.md
           - "In Progress":
               - federation/resolutions/index.md
-              - federation/resolutions/in-progress/034.md
       - "Minutes":
           - federation/minutes/index.md
           - "Recently":