docs: new & improved release docs

See toolshed/abra#793

docs/abra/cheat-sheet.md

@@ -70,7 +70,7 @@ To upgrade `abra` itself, run the following:
 $ abra upgrade
 ```
 
-Option flags: `--rc`
+Optional flags: `--rc`
 
 
 ### Upgrade a recipe
@@ -79,19 +79,13 @@ Option flags: `--rc`
 $ abra recipe upgrade $RECIPE`
 ```
 
-Option flags: `-x,y,z/--major,minor,patch`
-
-```
-$ abra recipe sync $RECIPE
-```
-
-Optional flags: `-x,y,z`
+Optional flags: `-x,y,z/--major,minor,patch`, `--commit`
 
 ```
 $ abra recipe release $RECIPE [$VERSION]
 ```
 
-Optional flags: `-p/--publish`, `-r/--dry-run`, `-x,y,z`
+Optional flags: `-r/--dry-run`, `-x,y,z`
 
 
 ### Manually restoring app data

docs/abra/hack.md

@@ -6,14 +6,14 @@ title: Hack
 
 Welcome to Hacking the Planet with `abra`! We're looking forward to see what you come up. If you have any questions, don't hesitate to ask 💖 However, please keep in mind that if any of your changes seems a bit controversial, it's probably best to come have a chat first to avoid heartache.
 
-In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging" based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
+In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging") based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
 
-In other words, we're happy to give you, as contributor, "the commit bit" (read/write permissions on the Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
+In other words, we're happy to grant contributors "the commit bit" (read/write permissions on our shared Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
 
 We maintain a "team" called "Co-operators" on our 2 main repositories:
 
-* [`git.coopcloud.tech/org/toolshed`](https://git.coopcloud.tech/org/toolshed/)
-* [`git.coopcloud.tech/org/coop-cloud`](https://git.coopcloud.tech/org/coop-cloud/)
+* [`git.coopcloud.tech/org/toolshed`](https://git.coopcloud.tech/toolshed/)
+* [`git.coopcloud.tech/org/coop-cloud`](https://git.coopcloud.tech/coop-cloud/)
 
 This gives you read/write access to all the repositories of the organisation.
 
@@ -30,14 +30,28 @@ Install [Go >= 1.16](https://golang.org/doc/install) and then:
 - `make build` to build. If this fails, run `go mod tidy`.
 - `./abra` to run commands
 - `make test` will run tests
-- `make install-abra` will install abra to `$GOPATH/bin`
-- `make install-kadabra` will install kadabra to `$GOPATH/bin`
+- `make install` will install abra to `$GOPATH/bin`
 - `go get <package>`, `go mod tidy` and `go mod vendor` to add a new dependency
 
 Our [Drone CI configuration](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/toolshed/abra/src/branch/main/Makefile) for more handy targets.
 
 Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
 
+### Super quick-start (Ubuntu Server)
+
+```bash
+cd 
+sudo apt update && DEBIAN_FRONTEND=noninteractive sudo apt install -y golang make git 
+git clone https://git.coopcloud.tech/toolshed/abra.git && cd abra 
+make build
+mkdir -p  ~/.local/bin/
+ln -sF $PWD/abra ~/.local/bin/abradev
+if [[ "$PATH" != *".local/bin"* ]]; then export PATH="$PATH:~/.local/bin/"; echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc; fi
+# Set up Spanish auto-completion
+LANG=es abra autocompletar bash | sed 's/abra/abradev/g' | sudo tee /etc/bash_completion.d/abra-dev
+abradev --help
+```
+
 ## Unit tests
 
 ### Run tests
@@ -85,23 +99,81 @@ The drone configuration was wired up as follows:
 
 Please ask `@decentral1se` or on the Matrix channels for SSH access to the machine.
 
+### Running manually on the CI server
+
+It's convenient to be able reproduce the CI server environment yourself by SSHing to the machine and running the integration tests. Here's how you do it.
+
+SSH config details:
+
+```
+Host int.coopcloud.tech
+  Hostname 51.159.168.99
+  User root
+  Port 22
+  IdentityFile ~/.ssh/<private-key-part>
+```
+
+Once you're in, you can run the following:
+
+```
+sudo -su abra
+cd
+tmux ls # if there is a session, run: tmux attach
+        # this way, we don't crash into each other
+        # when we're running tests
+./run-ci-int
+```
+
+You can also `cd abra` and run `bats ...` directly to trigger specific subsets
+of tests. You'll need to export the env vars at the bottom of the `run-ci-int`
+script to reproduce the same settings.
+
+```
+export ABRA_DIR="$HOME/.abra_test"
+export TERM=xterm
+export TEST_SERVER=default
+export ABRA_CI=1
+```
+
+And then ensuring a clean state and running with the same flags:
+
+```
+rm -rf "$ABRA_DIR"
+bats -Tp tests/integration --filter-tags \!dns --print-output-on-failure
+```
+
+See the [`run-ci-int`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/tests/run-ci-int) script for more.
+
+See below for more tips on how to run the tests.
+
 ### Running them locally
 
 #### Install dependencies
 
 We use [`bats`](https://bats-core.readthedocs.io/en/stable/) to run the tests. You can install the required dependencies with the following. You also need a working installation of Docker and Go >= 1.16 (not covered in this section).
 
-```
-apt install bats-file bats-assert bats-support jq make git
-```
-
-Unfortunately, the latest `bats` version in Debian stable does not have the "filter tests by tags" feature, which is very handy for running a subset of the tests. For this, we need to install `bats` from source. It's easy.
+##### Fedora 
 
 ```
-apt purge -y bats
-git clone https://github.com/bats-core/bats-core.git
-cd bats-core
-sudo ./install.sh /usr/local
+sudo dnf install bats
+```
+
+Unfortunately, the Fedora `bats` package doesn't include the libraries we need, so we need to clone those manually:
+
+```
+mkdir -p ~/.local/share/bats/
+cd ~/.local/share/bats
+git clone https://github.com/bats-core/bats-assert.git
+git clone https://github.com/bats-core/bats-file.git
+git clone https://github.com/bats-core/bats-support.git
+```
+
+Then, before running tests, set `export BATS_LIB_PATH=~/.local/share/bats/`
+
+##### Debian
+
+```
+apt install bats bats-file bats-assert bats-support jq make git
 ```
 
 #### Setup Test Server
@@ -110,31 +182,45 @@ For some tests an actual server is needed, where apps can be deployed. You can e
 
 ##### Remote swarm
 
+!!! warning
+
+    Right now, the test suite will check for a local swarm, see [abra/#769](https://git.coopcloud.tech/toolshed/abra/issues/769)
+
 ```
-export ABRA_TEST_DOMAIN="test.example.com"
+export TEST_SERVER="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
 ```
 
-`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
+There should also be a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
 
 ##### Local swarm
 
-When running the test suite localy you need a running docker swarm setup:
+!!! note
+
+    This is currently necessary even if you only want to run tests which don't need a server
+
+When running the test suite locally you need a running docker swarm setup:
 
 ```
 docker swarm init
 docker network create -d overlay proxy
 ```
 
-To use the local swarm set the foloowing env var:
+To use the local swarm set the following env var:
 
 ```
 export TEST_SERVER=default
 export ABRA_DIR="$HOME/.abra_test"
 ```
 
+Make sure that the user running the tests can access the docker socket e.g. by adding it to the `docker` group (security considerations apply).
+
 ### Run tests
 
+!!! note
+
+    You need to remember to compile your current version of `abra` via `make` before running the tests. See [abra/#770](https://git.coopcloud.tech/toolshed/abra/issues/770)
+
 Now you can run the whole test suite:
 
 ```
@@ -200,6 +286,81 @@ bats -Tp tests/integration --filter-status failed # re-run only failed
 
 If you're running into issues and want to debug stuff, you can pass `-x` to `bats` to trace all commands run in the test. You can add `echo '...' >&3` debug statements to your test to output stuff also.
 
+## Internationalisation (`i18n`)
+
+`abra` can be translated into other languages. We use a combination of [`gettext`](https://www.gnu.org/software/gettext/), [`weblate`](https://translate.coopcloud.tech) and some [intermediate automation](https://git.coopcloud.tech/toolshed/abra/src/commit/20909695e0e05c6251029dba270b3d4741aeb7a8/.drone.yml#L10-L29) to help developers and translators work together conveniently.
+
+### Developer workflow
+
+You just hack on `abra` as you normally would.
+
+If you need to add a string, use `i18n.G` to wrap it. See [`gotext`](https://github.com/leonelquinteros/gotext) for the full API.
+
+For example.
+
+```go
+i18n.G("my string")
+i18n.G("my string with err: %s", err)
+log.Debug(i18n.G("my string"))
+log.Info(i18n.G("my string with err: %s", err))  # N.B no log.Infof usage here
+```
+
+Then you need to update the `pkg/i18n/locales/abra.pot` file with your new strings for the translators.
+
+```bash
+apt install -y gettext
+go install -v -x github.com/snapcore/snapd/i18n/xgettext-go@2.57.1
+make i18n
+```
+
+Commit the changes. Ignore `*.mo` changes if they only update the generation timestamp.
+
+#### Resolving a merge conflict
+
+```
+git remote add weblate https://translate.coopcloud.tech/git/co-op-cloud/abra/
+git remote update weblate
+git merge weblate/main
+```
+
+Once you've resolved the conflict and pushed it, you'll need admin permissions on the Weblate repository to unlock it.
+
+### Translator workflow
+
+You can translate strings on [Weblate (`translate.coopcloud.tech`)](https://translate.coopcloud.tech). 
+
+It's also possible to translate using [`poedit`](https://poedit.net). Weblate is the recommended approach. 
+
+All translation files are located in [`pkg/i18n/locales`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/i18n/locales). Once translations are updated in weblate, they will be incorporated into the next release of `abra` automatically.
+
+In general, the workflow for translators is:
+
+- Code freeze announced for `abra` before release. Strings are not updated by developers and merge conflicts are avoided.
+- Translation work proceeds on [`translate.coopcloud.tech/projects/co-op-cloud/abra`](https://translate.coopcloud.tech/projects/co-op-cloud/abra/)
+- Translators ensure that the latest translation changes are synchronised to the `abra` git repository via [the settings](https://translate.coopcloud.tech/projects/co-op-cloud/abra/#repository)
+- Translators and developers will [install `abra` locally](/abra/hack/#super-quick-start-ubuntu-server) and test the latest changes
+- If all is well, we can release `abra`
+
+### Updating `abradev`
+
+If you followed the [Super quick-start instructions](/abra/hack/#super-quick-start-ubuntu-server) to install `abra`, then these are the instructions you need to update your local `abra` to get the latest changes from Weblate. Make sure to check that the latest Weblate changes are synchronised with the `abra` repository.
+
+```
+cd
+cd abra
+git pull origin main
+make build
+```
+
+### End-user workflow
+
+You simply export the `LANG` env var to match your desired translation.
+
+```
+export LANG=es
+abra -h
+```
+
 ## Using the `abra` public API
 
 Warning, there is currently no stability promise for the `abra` public API! Most of the internals are exposed in order to allow a free hand for developers to try build stuff. If people start to build things then we can start the discussion on what is useful to have open/closed and keep stable etc. Please let us know if you depend on the APIs!
@@ -239,7 +400,7 @@ func main() {
 
 Some tools that are making use of the API so far are:
 
-* [`kadabra`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/cmd/kadabra/main.go)
+* [`kadabra`](https://git.coopcloud.tech/toolshed/kadabra)
 
 ## Cross-compiling
 
@@ -276,9 +437,60 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 - Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-beta'`)
 - Make a new tag (e.g. `git tag -a x.y.z-beta`)
 - 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)
+- Wait until the build finishes successfully on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
+- Set your `GITEA_TOKEN` in your `.envrc` and run `make release` to release `abra`
 - Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
+- Clean up the changelog on the [releases
+  page](https://git.coopcloud.tech/toolshed/abra/releases) so it includes most
+  relevant changes. [See below](/abra/hack/#release-notes-text) for the
+  announcement text that needs to be inserted above the generated changelog.
+  You can use something like `git shortlog -e -s -n 0.XX.0-beta..HEAD` to get
+  the list of authors.
+- Make sure there is [a migration guide](/abra/upgrade/#migration-guides)
+  written in the docs (if necessary)
 - Check the release worked, (e.g. `abra upgrade; abra -v`)
+- Share [the standard announcement](/abra/hack/#general-announcement-text) on
+  our General chat and [fedi account](https://social.coop/@coopcloud)
+- Run away!
+
+#### 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 💖
+
+$git_shortlog_output
+```
+
+#### General announcement text
+
+```
+📢📢📢 abra v0.XX  is finally here 📢📢📢
+
+TLDR; `abra upgrade` 👍
+
+Upgrade docs:
+https://docs.coopcloud.tech/abra/upgrade/
+
+Changelog:
+https://git.coopcloud.tech/toolshed/abra/releases/tag/0.XX.0-beta
+
+0.XX.x-beta 👉 0.XX.x-beta migration guide:
+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
 
@@ -286,10 +498,18 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 
 We maintain a fork of [godotenv](https://git.coopcloud.tech/toolshed/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/toolshed/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/toolshed/abra/pulls/391) for more.
 
+### `docker/cli`
+
+We maintain a fork of [docker-cli](https://git.coopcloud.tech/toolshed/docker-cli/) because we needed to [patch port exposing](https://git.coopcloud.tech/toolshed/docker-cli/commit/2fbb22f65866ac97b47e4d47d8f855fee8c98e2a) to fix this [bug](https://github.com/docker/cli/issues/2407). Once the [fix was upstreamed](https://github.com/docker/cli/pull/6799) we can remove this fork again. 
+
 ### `docker/client`
 
 A number of modules in [pkg/upstream](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
 
+### `spf13/cobra`
+
+Our command library doesn't support `i18n` so we need to implement a work-around specifically for translating the `--help` command. See [`spf13/cobra#2359`](https://github.com/spf13/cobra/issues/2359) for more.
+
 ### `github.com/schultz-is/passgen`
 
 Due to [`toolshed/organising#358`](https://git.coopcloud.tech/toolshed/organising/issues/358).

docs/abra/index.md

@@ -8,8 +8,6 @@ title: Abra
 [![Go Report Card](https://goreportcard.com/badge/git.coopcloud.tech/toolshed/abra)](https://goreportcard.com/report/git.coopcloud.tech/toolshed/abra)
 [![Go Reference](https://pkg.go.dev/badge/coopcloud.tech/abra.svg)](https://pkg.go.dev/coopcloud.tech/abra)
 
-`abra` is the flagship client & command-line for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of operators and maintainers pleasant & convenient. It is libre software, written in Go and maintained and extended by the community :heart:
-
 `abra` is the flagship client & command-line tool for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of [operators](https://docs.coopcloud.tech/operators/) and [maintainers](https://docs.coopcloud.tech/maintainers/) pleasant & convenient. It is libre software, written in [Go](https://go.dev) and maintained and extended by the community 💖
 
 Once you've got `abra` installed, you can start your own Co-op Cloud deployment.

docs/abra/swarm.md

@@ -0,0 +1,55 @@
+---
+title: Swarm mode almanac
+---
+
+> !!! warning "This page is a Work In Progress :tm:"
+    A page to understand WTF is going on with [Swarm mode](https://docs.docker.com/engine/swarm/key-concepts/) and how we rely on it, how we might not rely on it and other related threads. Please add to this page as you see fit! If we can establish some shared understanding of what is going on under the hood, we can come up with a collective solution which meets everyones needs.
+
+## Support matrix
+
+In practice, this is what we currently rely on Swarm mode for.
+
+| Feature | Explanation |
+| ----------- | ----------- |
+| Encrypted secrets | When you run `abra secret generate`, it uses something like `printf foo | docker secret create foo -` under the hood. This feature only works if you have first run `docker swarm join`. Swarm mode [securely transports and stores your secret encrypted on the server](https://docs.docker.com/engine/swarm/secrets/#how-docker-manages-secrets). `docker compose` does not support encrypting or storing secrets because it only runs client-side. |
+| Template driver | If you use `template_driver: golang` in your `compose.yml` to insert secrets or environment variables into your configs, then you are using a template driver. This feature has almost 0 documentation and does not appear to be supported by [the actual Compose Spec](https://github.com/compose-spec/compose-spec/blob/main/08-configs.md) and is actually completely blocked by `docker compose` ([source](https://github.com/docker/compose/blob/f9828dfab909e9dd0dd489a49088c8619ec2ca7e/pkg/compose/create.go#L1095)). Several recipes use this feature and it seems quite crucial for our usage. |
+| Stacks | Firstly, [a service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) is key concept here. A stack is then a shared namespace of services with networks, volumes, configs etc. The concept of a stack is a [unique](https://docs.docker.com/engine/swarm/stack-deploy/) to Swarm mode. Any replacement for Swarm mode would have to implement this kind of namespacing feature for backwards compatibility purposes. See [`psviderski/uncloud#94`](https://github.com/psviderski/uncloud/discussions/94) for more. |
+| Orchestration | When you run `abra app deploy`, we're running a slightly customised `docker stack deploy` under the hood. Swarm mode is supposed to automagically handle zero downtime updates and rollbacks if things fail. However, we're seeing [the limitations of this approach](/abra/swarm/#limitations). |
+
+## Unsupport matrix
+
+| Feature | Explanation |
+| ----------- | ----------- |
+| Multi-node | It is possible but it doesn't seem like anyone in our community is really doing this. We believe the majority of Co-op Cloud installs are single node. There is also a lack of [CSI](https://github.com/olljanat/csi-plugins-for-docker-swarm?tab=readme-ov-file) support for coordinating storage across multiple hosts when using Swarm mode. This means we kind of throw out [the majority](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. |
+
+## Limitations
+
+* Swarm mode is still eerily underdeveloped and lacking features as a system. There are still some lurking network and stability bugs which are common. We're grateful for the undercover live reporting from people in-the-know adjacent to our network below. There are even folx inside Docker who are apparently calling it abandonware ([source](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-30235)). All this does not really put us at ease.
+
+!!! note "Docker whiskey leaks"
+
+    > https://www.mirantis.com/blog/mirantis-guarantees-long-term-support-for-swarm/
+    >
+    > Mirantis' relationship with "swarm" is very confusing! my understanding is that there are people (or one person? lol) at mirantis who do some work on the orchestration engine that is "docker swarm," but only to the extent that it supports mirantis' platform. i don't believe there's any active feature development beyond that. you're right that it's a misleading headline -- it sounds to me that they're just saying that they'll continue swarm support in their v3 kubernetes platform, not that they're committed to developing swarm as an orchestration system.
+    >
+    > Way back when (i guess in 2019? before my time!), docker sold off its enterprise platform which was called "swarm" to mirantis, so that's still a product that mirantis has and has developed in their way, but it's not the open-source swarm(kit) that's part of the docker cli. this is a good quick explanation: https://forums.docker.com/t/docker-swarmkit-and-the-mirantis-deal-not-docker-swarm/88886
+
+* The orchestration features of Swarm mode are opaque, causing failed deployments to be difficult to understand. This can cause a litany of a issues. For example, in the case where your database has been migrated and a rollback of your failing app doesn't support the new schema. This is being discussed extensively on [`organising#682`](https://git.coopcloud.tech/toolshed/organising/issues/682).
+
+## Potential alternatives
+
+* [`uncloud.run`](https://github.com/psviderski/uncloud): The Uncloud folks are creating a very different system. Something beyond compose but not k8s and not Swarm. This means they have to implement a lot of features of the orchestration from scratch. However, they're going for a nice approach: a straight-forward imperative deployment model (supports `depends_on` for predictable ordering during deployments). They're choosing which parts of the Compose Spec they implement and it's noteworthy that they [don't implement secrets yet](https://github.com/psviderski/uncloud/issues/75). See the [Compose support matrix](https://uncloud.run/docs/compose-file-reference/support-matrix) for more. They are however very focused on multi-node functionality. It's a system to [keep an eye on](https://github.com/psviderski/uncloud/milestone/1) with the hope that we can use some part of it in the future. Lines of communication [have been opened](https://github.com/psviderski/uncloud/discussions/255).
+
+* [`docker compose`](https://github.com/docker/compose): Plain old `docker compose`. A more elegant weapon for a more civilised age. It is however missing features we need such as encrypted secrets and `template_driver` support. There may be [more things missing](https://github.com/docker/compose/issues/11867). They are developing a promising [SDK](https://docs.docker.com/compose/compose-sdk/) exposes a public API for handling various operations. This would need some serious investigation and most likely some custom solutions for the features we're missing.
+
+## What we need
+
+* Something that is backwards compatible with our existing recipe configuration commons and the current deployments. We can't re-invent the wheel because we all rely on this system. So, we need to look towards incremental improvements or changes which are backwards compatible. We can always agree to change the config commons or some shared practices but then we need to establish a clear agreement with decision making. This is the social part.
+
+* Some way of conveniently using secrets when deploying services. This method should easily support working in a team which doesn't stray too far from our established Git Ops workflow of sharing `$ABRA_DIR`. They don't need to be encrypted and stored on the server (removing the need for Swarm mode handling) as long as they're mounted as secrets in the usual `/run/secret/<name>` manner at runtime.
+
+* Template driver support so we can template values into our configurations. This is used in enough recipes to warrant continued support.
+
+* A way to namespace services into a deployment, aka a "Docker Stack". This would appear to be a minor implementation detail after all is said and done. It's services all the way down and they have some linked networks/configs/volumes/etc. and a shared naming convention.
+
+* Some way to achieve [Fearless YunoHost-esque Upgrades](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-29302). In other words, some predictable way to deploy / upgrade / rollback and some way to intervene when things go wrong. It should be easy to understand for everyone and would enable real stability for operators. I think we want some sort of anti-orchestration implementation which is super simple.

docs/abra/trouble.md

@@ -23,6 +23,7 @@ Host example.com
 and your IdentityFile should be added to the authentication agent:
 
 ```
+eval `ssh-agent`
 ssh-add ~/.ssh/example@somewhere
 ```
 
@@ -101,3 +102,7 @@ Otherwise, you can try manually cloning the recipe repository to the correct loc
 ```
 $ git clone https://git.coopcloud.tech/coop-cloud/MyCoolRecipe.git ~/.abra/recipes
 ```
+
+## "only updates to Labels are allowed"
+
+See [Packaging handbook » What does "only updates to Labels are allowed" mean](/maintainers/handbook/#what-does-only-updates-to-labels-are-allowed-mean).

docs/abra/upgrade.md

@@ -53,6 +53,36 @@ And test things work.
 
 > General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)
 
+### `0.12.x-beta` -> `0.13.x-beta`
+
+* `abra recipe sync` went away. You now only need to run `upgrade`/`release`.
+  See [`#682`](https://git.coopcloud.tech/toolshed/abra/issues/682) for the
+  design details and
+  [here](/maintainers/handbook/#upstream-released-a-new-version-how-do-i-upgrade-the-recipe)
+  for the revised documentation. Thanks to `@iexos` for getting this out the
+  door!
+
+### `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,
+  e.g `TIMEOUT=180`. Recipe maintainers should remove defaults so that these
+  are not imposed on operators. See
+  [`#596`](https://git.coopcloud.tech/toolshed/abra/issues/596).
+
+* `--ignore-env-version` has gone away as a global flag. `--latest` is now
+  present on `abra app deploy`. See
+  [`#617`](https://git.coopcloud.tech/toolshed/abra/issues/617).
+
+* We now ensure that `$ABRA_DIR/servers` has stricter permissions (`0600`). See
+  [`#592`](https://git.coopcloud.tech/toolshed/abra/pulls/592) for more. No
+  migration step should be required.
+
 ### `0.9.x-beta` -> `0.10.x-beta`
 
 * `abra` will now write the app deployment version to the app env file
@@ -77,6 +107,10 @@ And test things work.
 * Auto-completion for `abra` is handled differently now. See `abra autocomplete
   --help` for more. The full help output is available for each specific shell,
   e.g. `abra autocomplete zsh --help`. It is now generated on the fly.
+  **WARNING**: you'll need to REMOVE your pre `v0.10.x` `abra` auto-complete
+  config for the new auto-complete to work. Check your `$SHELL` configuration
+  file (e.g. `.zshrc` for Zsh). See
+  [`#553`](https://git.coopcloud.tech/toolshed/abra/issues/553) for more.
 
 * Several commands now make use of the `--chaos/-C` commands, such as `abra app
   ps` and `abra app cp`. See `--help` for more.
@@ -133,6 +167,10 @@ And test things work.
 * It's now possible to set the character charset for a password. See
   [`#521`](https://git.coopcloud.tech/toolshed/abra/issues/521) for more.
 
+* `abra secret insert` now supports a `--file/-f` flag to support inserting
+  from file without using Bash-isms. See See
+  [`#555`](https://git.coopcloud.tech/toolshed/abra/issues/555) for more.
+
 ### `0.8.x-beta` -> `0.9.x-beta`
 
 None at this time.

docs/federation/finance.md

@@ -60,10 +60,6 @@ Finally, please let us know what your username/email is for your Open Collective
 
 #### FAQ
 
-##### Where are the bank details of federation members?
-
-Please see [`Finance.md` in the internal Federation Wiki](https://git.coopcloud.tech/Federation/organising/wiki/Finance)
-
 ##### What transfer type do we use for USD?
 
 `ACH`. If you see `Abartn`, that is the `ACH routing number`.

docs/federation/handbook.md

@@ -32,6 +32,8 @@ Here is some invitation boilerplate which you can use:
 >
 > There are no "stupid questions"! It's a space to inquire, be curious and have a good time and get to know each other.
 >
-> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/LqotfSJJRj69RcTtWmr7iw). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
+> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/VtyrLUl9RWaJGgEDrncQUw?view). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
 >
 > Hope to see you there! ☁️ 🌞 🖥️
+
+To work around Hedgedoc length limits, [we keep past content from the kite-flying pad here](./kite-flying-pad-archive).

docs/federation/index.md

@@ -38,6 +38,12 @@ This is the public facing page where we publish all things federation in the ope
 
     [Tools We Use](/federation/tools){ .md-button .md-button--primary }
 
+- __Shared Infrastructure Inventory__
+
+    Tools we maintain for the federation 🛠
+
+    [Tools We Maintain](/federation/infra){ .md-button .md-button--primary }
+
 - __Code of Co-operation__
 
     Be excellent to each other 💝

docs/federation/infra.md

@@ -0,0 +1,22 @@
+---
+title: Shared Infrastructure Inventory
+---
+
+## Shared repository for fedi maintainers
+
+> [coop-cloud-apps](https://git.coopcloud.tech/toolshed/coop-cloud-apps)
+
+## 2025 State of The Co-op Cloud Infra
+
+| service | server | recipe/app | notes |
+| --- | --- | --- | --- |
+| build.coopcloud.tech | `swarm-0.coopcloud.tech` | drone | should probably be moved to separate VPS |
+| (drone build runner) | `swarm-0.coopcloud.tech` | drone-docker-runner | should probably be moved to separate VPS |
+| git.coopcloud.tech |  `swarm-0.coopcloud.tech` | gitea | |
+| recipes.coopcloud.tech |  `swarm-0.coopcloud.tech` | [toolshed/recipes.coopcloud.tech](https://git.coopcloud.tech/coop-cloud/recipes.coopcloud.tech/)
+| recipes.coopcloud.tech/recipes.json | `swarm-0.coopcloud.tech` | [toolshed/recipes-catalogue-json](https://git.coopcloud.tech/toolshed/recipes-catalogue-json) | |
+| coopcloud.tech | `swarm-0.coopcloud.tech` | [toolshed/coopcloud.tech](https://git.coopcloud.tech/coop-cloud/coopcloud.tech/) | |
+| docs.coopcloud.tech | `swarm-0.coopcloud.tech` | [toolshed/docs.coopcloud.tech](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/) |  |
+| install.abra.coopcloud.tech | `swarm-0.coopcloud.tech` | [toolshed/abra/scripts/installer](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer) | |
+| sso.coopcloud.tech | `swarm-1.coopcloud.tech` | rauthy | |
+| translate.coopcloud.tech | `swarm-1.coopcloud.tech` | weblate | |

docs/federation/membership.md

@@ -18,6 +18,6 @@ title: Membership
 | [UTAW](https://utaw.tech) | -  | - | `@javielico:matrix.org` |
 | `@decentral1se` | Waiver | - | `@decentral1se` |
 | [ruangrupa](https://ruangrupa.id) | - | - | Henry `@babystepper:matrix.org` |
-| [Ammar](https://social.coop/@ammaratef45) | - | - | `@ammaratef45:matrix.org` |
-| [MIR](https://mirnet.org/) | ✅ | - | `@brooke:pub.solar` |
+| [RTM](https://resisttechmonopolies.online) | ✅ | - | `@ammaratef45:matrix.org` + `@linnealovespie:matrix.org`|
+| [MIR](https://mirnet.org/) | ✅ | - | `@sixsmith:matrix.org` |
 | [Red Abya Yala](https://abyayala.sutty.nl/) | - | - | `@fauno:sutty.nl` |

docs/federation/minutes/2022-03-03.md

@@ -100,8 +100,6 @@ Recap:
 
 ### decision-making process
 
-proposal: https://git.coopcloud.tech/Federation/Federation/wiki/Proposals
-
 - Trav: We adapted an old proposal for descision making process.
 - https://pad.autonomic.zone/s/MLafJE2jC#Overview
 - https://coopcloud.tech/blog/federation-proposal/

docs/federation/minutes/2025-12-28.md

@@ -0,0 +1,45 @@
+---
+title: 2025-12-28
+---
+
+## Coop-Cloud Meetup @ 39C3
+
+> Warning: this is no real protocol, since we did not really decide someone to
+> write down something (and what), but it was my try to summarize the
+> conclusive parts. For all attendees, please correct and extend on what i
+> wrote here, if something is missing or wrong :)
+
+### Talk about Coop-Cloud
+
+Simon and d1 are looking into the old state and maybe update it.
+
+### Alakazam workshop
+
+Tomorrow 16:15 at the coop-cloud table.
+
+### Daily things with coop-cloud (what is nice, what not)
+
+* Generally good experience
+* SSO stuff is cumbersome
+* Keeping an eye on recipe changes is a bit hard
+* Onboarding for new users could be easyer
+* Catalog has structural problems
+* All are using several workarounds
+* Upgrading a recipe is cumbersome (there is a proposal to make that better, just has to be implemented)
+
+### More cooperation in general/ reflect on kiteflying / talk about finances:
+
+* Me try to do it once a month with more static topics
+* The radmin role would maybe help to fix to get people payed for stuff through that
+* Draft from p4u1 and d1
+* Maybe a proposal gets made by kawaiipunk to rise the wage for internal tasks (discussions will follow to refine that idea)
+* We want to implement the maintainers proposal to more recipes
+* We should implement default guidelines for cooperation/contribution for the recipes, which can be "overwritten" by each reipe maintainers
+* We want to experiment with automated testing, for recipes, here it would be great to have some kind of a defined list of what should be tested
+* Maybe we could implement a language server for abra
+* Idea: Workaround sharing session or blog write ups about the workarounds used
+* Idea: move away from the env file in the future via defining a standard over alakazam without breaking the env (like upstream alakazam)
+
+### Political Statement in the Documentation
+
+d1 puts survey answers to a text and then we work together and decide it in a kiteflying.

docs/federation/organisers.md

@@ -10,7 +10,7 @@ Welcome to the organisers guide! Organisers are folks who focus on the social wo
 
     One-stop shop for all you need to know to organise in the community :sparkles:
 
-    [Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
+    [Read Handbook](/federation/handbook){ .md-button .md-button--primary }
 
 - __Say Hello First__
 

docs/federation/resolutions/in-progress/035.md

@@ -0,0 +1,33 @@
+---
+title: "Resolution 035: Budget 016: Sutty Website Proposal"
+---
+
+- Topic: Budget 016: Sutty Website Proposal
+- Date: 2026-02-12
+- Deadline: 2026-02-26
+- Size: Large
+
+## Summary
+
+Budget 016 proposes to:
+
+1. Compensate Sutty and Co-op Cloud community members `@edu` & `@eli` 250 USD (500 USD total) each according to their own proposed compensation.
+1. Compensate `@diatom` for up to 30 hours to participate in the generative process as Co-op Cloud community delegate.
+
+Please see [the full proposal text](https://vvvvvvaria.org/~decentral1se/cc/CoopCloud-2025WebsiteProposal-Sutty.pdf) for more details. See `Capítulo 3 > Resources estimations` for the section regarding financial estimations. The Co-op Cloud community and federation are to be consulted during this process for decision making around choosing a new website proposal. `@diatom` agrees to be a bridge between the work of `@edu`/`@eli` and the Co-op Cloud community.
+
+## Details (Budget 016)
+
+This resolution follows the Good Work of `@sef`/`@edu`/`@eli` in carrying out the Co-op Cloud Community Website Survey. The idea is that `@edu` and `@eli` (with the blessing of `@sef`) will now bring forward a concrete proposal for the new Co-op Cloud website based on their proposed generative process. Please see [the full proposal text](https://vvvvvvaria.org/~decentral1se/cc/CoopCloud-2025WebsiteProposal-Sutty.pdf) for all details.
+
+#### Budget
+
+`@edu`/`@eli`/`@diatom` will carry out this work.
+
+Please join `#coop-cloud-new-website:autonomic.zone` to participate in this process. All community members are welcome.
+
+The budget total is:
+
+* 500 USD (423 EUR)
+* 30 hrs * 20 EUR = 600 EUR
+* **Total**: 1023 EUR

docs/federation/resolutions/in-progress/037.md

@@ -0,0 +1,26 @@
+---
+title: "Resolution 037: Adopt alakazam as an official project in the Co-op Cloud Federation"
+---
+
+- Topic: Resolution 037: Adopt alakazam as an official project in the Co-op Cloud Federation
+- Date: 12-02-2026
+- Deadline: 26-02-2026
+- Size: medium
+
+## Summary
+
+We want to adopt the abra wrapper Alakazam (https://git.coopcloud.tech/moritz/alakazam) , which is used by KolliCloud (https://kollicloud.de) as an official project in the Co-op Cloud Federation
+
+## Details
+
+As we already disscussed on our Meetup and the Alakazam workshop at 39C3 end of 2025, we want to adopt the abra wrapper Alakazam (https://git.coopcloud.tech/moritz/alakazam), which is used by KolliCloud (https://kollicloud.de) as an official project in the Co-op Cloud Federation. This way, we want to start collaborative effort on teaching, writing docs, writing tests.
+
+This includes the following (in the long run):
+
+* tranfering the Alakazam repository to https://git.coopcloud.tech/toolshed
+* creating a space in the docs for alakazam and moving the contents of the readme and the nessecary contents of https://wiki.local-it.org/s/kollicloud-wiki/doc/installation-wVp2LfBbg7
+* get others to try alakazam (future Kite-Flying sessions for this)
+* write tests for alakazam
+* implement the option to use more than one deployment of the same application in one instance
+* migrate alaconnect.yml files for the recipe (we have to figure out how multiple instances would allow this in regards to the multiple same apps in one instance)
+* migrate the features (that makes sense) into abra

docs/federation/resolutions/passed/001.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 001"
+title: "Resolution 001: Decision-Making Process"
 ---
 
 - Topic: Decision Making Process
@@ -13,13 +13,13 @@ Institute descision making process as per below. Special consensus voting in org
 
 ### Decision Making Process
 
-* Write up a proposal using the below template, and add to the [Proposals wiki page](https://git.coopcloud.tech/Federation/Federation/wiki/Proposals).
+* Write up a proposal using the below template, and add to the [Resolutions documentation "in-progress" section](https://docs.coopcloud.tech/federation/resolutions/).
 * Specify if they are a large or medium proposal
 * Votes are done via emoji-reaction in the Community Organising Matrix channel (<https://matrix.to/#/#coopcloud-comm-org:autonomic.zone>)
-* List the decision on the [decisions page](https://docs.coopcloud.tech/federation/resolutions) on our documentation
 * Decisions can be split intro three categories: Small, Medium and Large.
 * Votes can be in favour :+1:, against :-1: (block),  or abstain :shrug:
 * Announce the result in the [Federation chat (#coop-cloud-fedi:autonomic.zone)](https://docs.coopcloud.tech/intro/contact/#matrix) and record it on the [decisions page](https://docs.coopcloud.tech/federation/resolutions) of the documentation
+* Move it to the [Resolutions documentation "passed" section](https://docs.coopcloud.tech/federation/resolutions/).
 
 ### Types of Proposals
 

docs/federation/resolutions/passed/002.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 002"
+title: "Resolution 002: Membership/Dues"
 ---
 
 * Topic: Membership/Dues

docs/federation/resolutions/passed/003.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 003"
+title: "Resolution 003: Paid Work"
 ---
 
 * Topic: Paid work

docs/federation/resolutions/passed/004.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 004"
+title: "Resolution 004: Budgeting (+ Budget 001: Monlthy Meetings)"
 ---
 
 * Topic: Budget 001: Budgeting

docs/federation/resolutions/passed/005.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 005"
+title: "Resolution 005: Public federation membership"
 ---
 
 * Topic: Public federation membership, notes and decisions
@@ -18,4 +18,4 @@ The following federation info will be made public on [`docs.coopcloud.tech/feder
 
 ### Details
 
-This will make the process of documenting easier to mutualise and increase transparency for those interested in joining. The [`git.coopcloud.tech/Federation`](https://git.coopcloud.tech/Federation/Federation/wiki/) wiki can still be used for storing private details such as bank account information. If members do not want to be listed, they can do so even when this decision passes.
+This will make the process of documenting easier to mutualise and increase transparency for those interested in joining. The `git.coopcloud.tech/Federation` wiki (**NOTE(d1) from the future**: this repository is now decommissioned) can still be used for storing private details such as bank account information. If members do not want to be listed, they can do so even when this decision passes.

docs/federation/resolutions/passed/006.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 006"
+title: "Resolution 006: Budget 002 Resolution Writing-up"
 ---
 
 - Budget 002: Resolution Writing-up
@@ -11,7 +11,7 @@ title: "Resolution 006"
 
 Agree Budget 002, for €100 for @decentral1se to write up 2 resolutions.
 
-### Details (Budget YYY)
+### Details (Budget 002)
 
 **Budget amount**: EUR 100
 

docs/federation/resolutions/passed/007.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 007"
+title: "Resolution 007: Dues waiver for Doop.coop"
 ---
 
 - Topic: 1 year dues waiver for Doop.coop

docs/federation/resolutions/passed/008.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 008"
+title: "Resolution 008: Budget 003 Paying Invoices"
 ---
 
 - Topic: Budget 003 Paying invoices

docs/federation/resolutions/passed/009.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 009" 
+title: "Resolution 009: Federation common fund buffer" 
 ---
 
 - Topic: Federation common fund buffer

docs/federation/resolutions/passed/010.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 010"
+title: "Resolution 010: Budget 004 Critical fixes"
 ---
 
 - Topic: Budget 004: Critical fixes

docs/federation/resolutions/passed/011.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 011" 
+title: "Resolution 011: Budget 005: Backup improvements" 
 ---
 
 - Topic: Budget 005: Backup improvements

docs/federation/resolutions/passed/012.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 012"
+title: "Resolution 012: Budget 006: Abra integration test suite"
 ---
 
 - Budget 006: Abra integration test suite

docs/federation/resolutions/passed/014.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 014"
+title: "Resolution 014: Budget 008: Critical Fixes"
 ---
 
 - Topic: Budget 008: Critical Fixes

docs/federation/resolutions/passed/015.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 015"
+title: "Resolution 015: Klasse and Methode joins"
 ---
 
 - Topic: Klasse & Methode joins the Co-op Cloud Federation

docs/federation/resolutions/passed/016.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 016"
+title: "Resolution 016: Budget 008: Backup-bot-two …"
 ---
 
 - Topic: Budget 008: Backup-bot-two Documentation and Specification

docs/federation/resolutions/passed/017.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 017"
+title: "Resolution 017: BeWater joins"
 ---
 
 - Topic: BeWater joins the Co-op Cloud Federation

docs/federation/resolutions/passed/018.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 018"
+title: "Resolution 018: EOTL joins"
 ---
 
 - Topic: EOTL joins the Co-op Cloud Federation

docs/federation/resolutions/passed/019.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 019"
+title: "Resolution 019: Karrot joins"
 ---
 
 - Topic: Karrot joins the Co-op Cloud Federation

docs/federation/resolutions/passed/020.md

@@ -1,8 +1,8 @@
 ---
-title: "Resolution 020"
+title: "Resolution 020: Budget 010: Abra integration test suite"
 ---
 
-- Topic: Budget 10: Abra integration suite automation
+- Topic: Budget 010: Abra integration suite automation
 - Date: 04-04-2024
 - Deadline: 18-04-2024
 - Size: Large

docs/federation/resolutions/passed/021.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 021"
+title: "Resolution 021: Budget 011: Migrate to Cobra"
 ---
 
 - Topic: Budget 011: Migrate to Cobra

docs/federation/resolutions/passed/022.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 022"
+title: "Resolution 022: Ammar joins"
 ---
 
 - Topic: Ammar joins the Co-op Cloud Federation

docs/federation/resolutions/passed/023.md

@@ -1,5 +1,5 @@
 ---
-title: Resolution 023
+title: "Resolution 023: Budget 012: … new Co-op Cloud website"
 ---
 
 - Topic: Budget 012: Feedback gathering and content architecture for the new Co-op Cloud website

docs/federation/resolutions/passed/024.md

@@ -1,4 +1,6 @@
-# Resolution 024: Budget: 013: Reintroduce kite-flying
+---
+title: "Resolution 024: Budget: 013: Reintroduce kite-flying"
+---
 
 - Topic: Reintroduce paid kite-flying hour
 - Date: 2024-10-30

docs/federation/resolutions/passed/025.md

@@ -1,4 +1,6 @@
-# Resolution 025 Maintainers Proposal
+---
+title: "Resolution 025 Maintainers Proposal"
+---
 
 - Topic:  Maintainers Proposal
 - Date: 05-12-2024

docs/federation/resolutions/passed/026.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 026"
+title: "Resolution 026: Budget 014: Backpay for v0.10.x abra release work"
 ---
 
 - Topic: Budget 014: Backpay for `v0.10.x` abra release work

docs/federation/resolutions/passed/027.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 027"
+title: "Resolution 027: MIR joins"
 ---
 
 - Topic: MIR joins the Co-op Cloud Federation

docs/federation/resolutions/passed/028.md

@@ -1,4 +1,6 @@
-# Resolution 028: Red Abya Yala joins the Co-op Cloud Federation
+---
+title: "Resolution 028: Red Abya Yala joins the Co-op Cloud Federation"
+---
 
 - Topic: Red Abya Yala joins the Co-op Cloud Federation
 - Date: 16-01-2025

docs/federation/resolutions/passed/029.md

@@ -1,4 +1,6 @@
-# Resolution 29 Budget 14: Federation Radmin
+---
+title: "Resolution 029: Budget 014: Federation Radmin"
+---
 
 - Topic: Establish Budget 14, to pay for up to 12 hours a month of "radmin" (radical administration) work, to help the federation run smoother, for an initial period of 12 months.
 - Date: 05-04-2025

docs/federation/resolutions/passed/031.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 031"
+title: "Resolution 031: Critical fixes amended process"
 ---
 
 - Topic: Critical fixes amended process

docs/federation/resolutions/passed/032.md

@@ -0,0 +1,22 @@
+---
+title: "Resolution 032: RTM joins"
+---
+
+- Topic: RTM joins Coopcloud
+- Date: 2025-06-30
+- Deadline: 2025-07-10
+- Size: Large
+
+### Summary
+
+Ammar's membership was approved in [Resolution 022](/federation/resolutions/passed/022).
+
+Since the establishment of RTM (Resist Tech Monopolies) collective in Seattle, Ammar has been unofficially representing the collective with coopcloud and vice versa.
+	
+### Details
+	
+RTM relies on the coop-cloud stack to host and manage their infrastructure, with the possibility of expanding this infrastructure to serve other communities and groups as the needs are identified and the capacity of the collective grows.
+
+In a loomio decision, the collective approved pursuing a membership with the federation and Ammar is both happy to vouch and to yield their membership to the group.
+
+This way this decision doesn't affect the total number of members.

docs/federation/resolutions/passed/033.md

@@ -0,0 +1,33 @@
+---
+title: "Resolution 033: Changing OpenCollective fiscal host"
+---
+
+- Topic: Changing OpenCollective fiscal host to Platform6
+- Date: 2025-07-16
+- Deadline: 2025-07-30
+- Size: Large
+
+## Summary
+
+Currently, the Open Collective "fiscal host" for Co-op Cloud is [Autonomic
+co-operative](https://autonomic.zone).
+
+This resolution proposes switching fiscal host to [Platform
+6](https://platform6.coop), by transferring our funds from Autonomic to
+Platform 6, and changing our registered fiscal host on Open Collective.
+
+This resolution will close Budget 001, because Platform 6 will take a fixed 5%
+of income, instead of being paid hourly.
+
+## Details
+
+Autonomic has been the fiscal host for Co-op Cloud since the first project
+funding was received.
+
+Since then, Autonomic has less capacity for finance administration work -- and
+Co-op Cloud is now managed by a democratic federation.
+
+So, to open up more capacity for project finance administration work, and to
+further decentralise Co-op Cloud organising from Autonomic, we're proposing
+Platform 6. Platform 6 have been fiscal host for co-operative projects
+including [meet.coop](https://meet.coop) and [wiki.cafe](https://wiki.cafe).

docs/federation/resolutions/passed/034.md

@@ -0,0 +1,20 @@
+---
+title: "Resolution 034: Extra budget for Escuela Común recipes"
+---
+
+- Topic: Budget 015: Extra budget for recipes needed by Escuela Común
+- Date: 2025-10-27
+- Deadline: 2025-11-10
+- Size: medium
+
+## Summary
+
+Budget 015 for 20 estimated hours of work towards Escuela Común, **to be reimbursed** from next year's budget from the Sepal fund to the Co-op Cloud Federation Common Fund.
+
+## Details
+
+As Escuela Común 2026 planning proceeds, many `abra` bugs were closed, and we even gained the translations feature, but we've realised that we'll need at least one extra recipe to support Escuela's organizing: [`tellaweb`](https://github.com/Horizontal-org/tellaweb).
+
+This work has been supported by the Sepal fund we're sharing with Escuela Común. The budget allocated for this year has been used in full, so we're requesting the Federation to allocate budget from its own funds to cover for 20 estimated hours, to be reimbursed from next year's budget, that will be available on April 2026.
+
+`@3wc` will carry out this work.

docs/federation/resolutions/passed/036.md

@@ -0,0 +1,28 @@
+---
+title: "Resolution 036: Democratic Tech Fund joins the Co-op Cloud Federation"
+---
+
+- Topic: Resolution 036: Democratic Tech Fund joins the Co-op Cloud Federation
+- Date: 2026-01-19
+- Deadline: 2026-02-02
+- Size: Large
+
+## Summary
+
+The Democratic Tech Fund (DTF) is a Project-In-The-Making which has close affinity with Co-op Cloud in culture and stated goals. `@mikemh` and `@wtebbens` are active members of the community and can represent the Democratic Tech Fund. The DTF would like to join the Co-op Cloud Federation in order to establish a solid base for future collaboration.
+
+The DTF is set up as a co-operative federation, with multi-stakeholder membership: to allow both individual as organisational membership, operational members (i.e. workers), collaborator members, council of steward members (elected) and institutional members (public and private funders).
+
+A brief summary of the the intended goals of the DTF are as follows:
+
+* **Build and provide the tech**: Generating working configurations of tech infrastructure and services that address actual, perceived needs, drawing on the reserves of free-libre open- source software and constructing practices of material infrastructure that are under the review and steering of the communities they service. 
+
+* **Mobilise awareness towards adoption**: highlighting the clear and present danger and our collective capacity to resist, re-make and re-imagine. There's a need for campaign work, media and visuals, and for intelligence and news about what has already been done. 
+
+* **Build the community**: nurturing local, regional and trans-regional communities and networks that are capable to articulate these alternatives, to make the change together and to sustain the economic base for radically re-oriented infrastructure.
+
+Please see the latest Work-In-Progress [DTF concept note - v0.3](https://oficina.commonscloud.coop/s/No93qBkpxAsgYqE) for more details. Founding members include the [Free Knowledge Institute](https://freeknowledge.eu), [Commons Network](https://www.commonsnetwork.org) and [Fundación Platoniq / Goteo.org](https://goteo.org). The Free Knowledge Institute is also the fiscal host of the DTF. Please see the website of the [DTF](https://democratictech.fund) itself for more information.
+
+DTF are happy to pay the current recommended federation membership fee.
+
+Please feel free to join `#dtf2026:matrix.org` to keep up with DTF project developments.

docs/federation/resolutions/stalled/013.md

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 013" 
+title: "Resolution 013: Budget 007: Operator sync" 
 ---
 
 !!! note

docs/federation/resolutions/stalled/030.md

@@ -1,4 +1,6 @@
-# Co-op Cloud resolution 030: docs / naming survey
+---
+title: "Co-op Cloud resolution 030: Budget XXX: Docs / naming survey"
+---
 
 - Topic: Budget for a survey about the Co-op Cloud documentation 
 - Date: 2025-04-03

docs/federation/tools.md

@@ -3,9 +3,10 @@ title: Digital tools
 ---
 
 - [Public documentation](https://docs.coopcloud.tech/federation)
-- [Organising repository (private)](https://git.coopcloud.tech/Federation/organising)
-- [Wiki (private)](https://git.coopcloud.tech/Federation/organising/wiki)
 - [Git hosting](https://git.coopcloud.tech/)
 - [Matrix Space](https://matrix.to/#/#coop-cloud-space:autonomic.zone)
 - [Website](https://coopcloud.tech/)
+- [Single Sign On](https://translate.coopcloud.tech/)
+- [Translation](https://translate.coopcloud.tech/)
+- [Sheets and time tracking](https://sheets.coopcloud.tech/)
 - [Drone CI/CD](https://build.coopcloud.tech)

docs/intro/comparisons.md

@@ -175,6 +175,29 @@ handful of popular team collaboration apps.
 - 👎 It is not designed to be a general specification.
 - 👎 Hard to share configurations into the commons.
 - 👎 Limited library of apps.
-- 👎 Uses *OpenNebula*, *Ansible*, and *Puppet* as underlying technologies.
+- 👎 Uses Ansible (see above)
 - 👎 Appears to be only a team of two people.
 - 👎 Appears to be inactive on Mastodon and limited GitLab activity. 
+
+### Dokploy 
+
+[Dokploy](https://dokploy.com/) (who have [their own comparison](https://docs.dokploy.com/docs/core/comparison)).
+
+- 👍 Supports builds from Git repositories, Dockerfiles, Nixpacks, and Buildpacks like Heroku and Paketo.
+- 👍 [~100 application templates](https://docs.dokploy.com/docs/core/templates)
+
+- 👎 [Bespoke TOML config](https://github.com/Dokploy/templates?tab=readme-ov-file#templatetoml-structure)
+- 👎 Community on Discord and Github discussions
+- 👎 Freemium / open-core model
+
+### Cosmos Cloud 
+
+[Cosmos Cloud](https://cosmos-cloud.io/), "The cloud doesn't need to be someone else's computer"
+
+- 👍 [Native client apps](https://cosmos-cloud.io/clients/)
+- 👍 Built-in VPN 
+
+- 👎 Community on Discord, Github discussions, and Reddit
+- 👎 "Up to 19 users" even on paid plans
+- 👎 Freemium / open-core model
+- 👎 ["Commons clause"](https://github.com/azukaar/Cosmos-Server/blob/master/LICENCE)

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:
@@ -86,6 +92,16 @@ Because configurations are maintained in-repository by maintainers, we version t
 export NGINX_CONFIG_VERSION=v1
 ```
 
+!!! warning
+
+    It is **very important** that the naming convention of the config matches
+    the whole way down. In the above example, that is `nginx_config` in the
+    `configs:` stanza, `nginx_config` in `name:
+    ${STACK_NAME}_nginx_config_${NGINX_CONFIG_VERSION}` and finally
+    `NGINX_CONFIG_VERSION` in the `abra.sh`. This is the naming convention that
+    `abra` will perform to carry out the lookup of all matching names/values.
+    See [`#693`](https://git.coopcloud.tech/toolshed/abra/issues/693) for more.
+
 ## Manage environment variables
 
 !!! warning
@@ -124,6 +140,45 @@ 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
+   ```
+   
+   Note: If you need to break something, make sure to add a [release note](/maintainers/handbook/#how-do-i-write-version-release-notes) explaining to operators what they should change before upgrading.
+
+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
@@ -256,10 +311,36 @@ file_env "DB_PASSWORD"
 Sometimes the containers don't even have Bash installed on them. You had better just use `/bin/sh` or, in your entrypoint script, install Bash :upside_down: The entrypoint secrets hack listed above doesn't work in this case (as it requires Bash), so instead you can just do `export FOO=$(cat /run/secrets/<secret-name>)`.
 
 
+## Templating
+
+### Templating domain names in the `.env.sample`
+
+`<recipe>.example.com` will be transformed into the end-user app domain when `abra app new` is run.
+
+### Templating domain names in release notes
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.11.x series of `abra`.
+
+`<recipe>.example.com` will be transformed into the end-user app domain when `abra app upgrade` shows release notes.
+
 ## How do I reference services in configs?
 
 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 `STACK_NAME` dragons 🐉"
+
+    `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.
+
+    ```yaml
+      services:
+        web:
+          image: nginx:1.29.3
+          environment:
+            - STACK_NAME
+    ```
+
 ## How are recipes versioned?
 
 We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
@@ -272,111 +353,143 @@ Therefore, we maintain an additional version part, in front of the project versi
 
 In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3` to `1.15.3`, we still publish `1.1.0+1.15.3` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
 
-## How do I release a new recipe version?
+## Upstream released a new version, how do I upgrade the recipe?
 
-The commands uses for dealing with recipe versioning in `abra` are:
-
-- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
-- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
-- `abra recipe release`: publish a git tag for the recipe repo
-
-The `abra` recipe publishing commands have been designed to complement a semi-automatic workflow. If `abra` breaks or doesn't understand what is going on, you can always finish the process manually with a few Git commands and a bit of luck. We designed `abra` to support this way due to the chaotic nature of container publishing versioning schemes.
-
-Let's take a practical example, publishing a new version of [Wordpress](https://git.coopcloud.tech/coop-cloud/wordpress).
-
-If we run `abra recipe upgrade wordpress` (at time of running), we end up with a prompt to upgrade Wordpress to `5.9.0`. We can skip the database upgrade for now. Here is what that looks like:
+`abra` can help you so you don't have to update the image tags in the compose files manually. Let us for example make an upgrade of [Wordpress](https://git.coopcloud.tech/coop-cloud/wordpress). Run:
 
 ```
-➜  ~ abra recipe upgrade wordpress
-? upgrade to which tag? (service: app, image: wordpress, tag: 5.8.3) 5.9.0
-? upgrade to which tag? (service: db, image: mariadb, tag: 10.6) skip
-WARN[0004] not upgrading mariadb, skipping as requested
+$ abra recipe upgrade wordpress
 ```
 
-Now, what happened? `abra` queried the upstream container repositories of all the images listed in the Wordpress recipe configuration and checked if there are new tags available. Once you make some choices on the prompt, `abra` will update the recipe configurations. Let's take a look by running `cd ~/.abra/recipes/wordpress && git diff`:
+If we run `abra recipe upgrade wordpress` (at time of running), we end up with a prompt to upgrade Wordpress to `6.9.1` and mariadb to `12.2`. Commit the changes when asked. Here is what that looks like:
 
-```diff
+```
+$ abra recipe upgrade wordpress
+? upgrade to which tag? (service: app, image: wordpress, tag: 6.9.0) 6.9.1
+? upgrade to which tag? (service: db, image: mariadb, tag: 12.1) 12.2
+WARN unable to read tag for image atmoz/sftp, is it missing? skipping upgrade for ftp
+INFO wordpress currently has these unstaged changes 👇
 diff --git a/compose.yml b/compose.yml
-index 1618ef5..6cd754d 100644
+index b3c3871..07d0a54 100644
 --- a/compose.yml
 +++ b/compose.yml
 @@ -3,7 +3,7 @@ version: "3.8"
-
+ 
  services:
    app:
--    image: "wordpress:5.8.3"
-+    image: "wordpress:5.9.0"
+-    image: "wordpress:6.9.0"
++    image: "wordpress:6.9.1"
      volumes:
        - "wordpress_content:/var/www/html/wp-content/"
      networks:
+@@ -65,7 +65,7 @@ services:
+         - "coop-cloud.${STACK_NAME}.version=2.17.0+6.9.0"
+ 
+   db:
+-    image: "mariadb:12.1"
++    image: "mariadb:12.2"
+     volumes:
+       - "mariadb:/var/lib/mysql"
+     networks:
+? commit changes? Yes
+INFO committed changes as 'chore: update image tags'
 ```
 
+Here is a rundown of what happened:
+
+- `abra` queried the upstream container repositories of all the images listed in the Wordpress recipe configuration and checked if there are new tags available
+- Once you make some choices on the prompt, `abra` will update the recipe configurations and show you the diff
+- If you choose to, a new commit containing the changes will be created
+
 !!! warning "Here be versioning dragons"
 
-    `abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/toolshed/tagcmp) for more info on how we implement image parsing.
+    As you can see with `atmoz/sftp`, `abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/toolshed/tagcmp) for more info on how we implement image parsing.
 
-Next, we need to update the label in the recipe, we can do that with `abra recipe sync wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading from `5.8.3` -> `5.9.0`, it is a minor release, so we choose `minor`:
+You will probably want to [test the upgrade](#how-are-new-recipe-versions-tested) now. Afterwards, you can release the upgraded recipe as outlined in the next section.
+
+## How do I release a new recipe version?
+
+!!! warning "Watch out for old versions of abra 🚧"
+
+    This section describes the release process with `abra` version `0.13.x`.
+    For older version, you will need to use these commands:
+    ```
+    abra recipe sync <recipe>
+    abra recipe release <recipe> -p
+    ```
+
+After upgrading the image tags and/or making some other changes to the recipe, you may want to release a new version. This can be done with
 
 ```
-➜  wordpress (master) ✗ abra recipe sync wordpress
-...
-INFO[0088] synced label coop-cloud.${STACK_NAME}.version=1.1.0+5.9.0 to service app
+abra recipe release
 ```
 
-Once again, we can run `cd ~/.abra/recipes/wordpress && git diff` to see what `abra` has done for us:
+Continuing our Wordpress example above, we can start the release process with `abra recipe release wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading Wordpress from `6.9.0` -> `6.9.1`, and the minor MariaDB upgrade does not change anything in our case, we consider this a `patch` release. Next, you will be prompted for release notes. Since there are no breaking changes or otherwise noteworthy changes in this upgrade, you can leave them empty.
 
-```diff
-diff --git a/compose.yml b/compose.yml
-index 1618ef5..4a08db6 100644
---- a/compose.yml
-+++ b/compose.yml
-@@ -3,7 +3,7 @@ version: "3.8"
+Here is what you will see:
 
- services:
-   app:
--    image: "wordpress:5.8.3"
-+    image: "wordpress:5.9.0"
-     volumes:
-       - "wordpress_content:/var/www/html/wp-content/"
-     networks:
-@@ -48,7 +48,7 @@ services:
-         #- "traefik.http.routers.${STACK_NAME}.rule=HostRegexp(`{subdomain:.+}.${DOMAIN}`, `${DOMAIN}`)"
-         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
--        - "coop-cloud.${STACK_NAME}.version=1.0.2+5.8.3"
-+        - "coop-cloud.${STACK_NAME}.version=1.1.0+5.9.0"
-         - "backupbot.backup=true"
-         - "backupbot.backup.path=/var/www/html"
+```
+$ abra recipe release wordpress
+
+You need to make a decision about what kind of an update this new recipe
+version is. If someone else performs this upgrade, do they have to do some
+migration work or take care of some breaking changes? This can be signaled in
+the version you specify on the recipe deploy label and is called a semantic
+version.
+
+The latest published version is 2.17.0+6.9.0.
+
+┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ SERVICE ┃  2.17.0+6.9.0   ┃ PROPOSED CHANGES ┃
+┣━━━━━━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━┫
+┃ app     ┃ wordpress:6.9.0 ┃ wordpress:6.9.1  ┃
+┃ db      ┃ mariadb:12.1    ┃ mariadb:12.2     ┃
+┗━━━━━━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━┛
+
+Here is a semver cheat sheet (more on https://semver.org):
+
+    major: new features/bug fixes, backwards incompatible (e.g 1.0.0 -> 2.0.0).
+           the upgrade won't work without some preparation work and others need
+           to take care when performing it. "it could go wrong".
+
+    minor: new features/bug fixes, backwards compatible (e.g. 0.1.0 -> 0.2.0).
+           the upgrade should Just Work and there are no breaking changes in
+           the app and the recipe config. "it should go fine".
+
+    patch: bug fixes, backwards compatible (e.g. 0.0.1 -> 0.0.2). this upgrade
+           should also Just Work and is mostly to do with minor bug fixes
+           and/or security patches. "nothing to worry about".
+
+? select recipe version increment type patch
+INFO synced label coop-cloud.${STACK_NAME}.version=2.17.1+6.9.1 to service app
+? add release note? (leave empty to skip) 
+INFO new release published: https://git.coopcloud.tech/coop-cloud/wordpress.git/src/tag/2.17.1+6.9.1
 ```
 
-You'll notice that `abra` figured out how to upgrade the Co-op Cloud version label according to our choice, `1.0.2` -> `1.1.0` is a minor update.
+Here is a rundown of what happened:
 
-At this point, we're all set, we can run `abra recipe release --publish wordpress`. This will do the following:
-
-1. run `git commit` the new changes
-1. run `git tag` to create a new git tag named `1.1.0+5.9.0`
-1. run `git push` to publish changes to the Wordpress repository
+- with the choice of patch upgrade, `abra` determined the new recipe version label to be `2.17.1+6.9.1`
+- the label is updated in `compose.yml`
+- the changes to the label (and release notes if there are any) are committed
+- a new annotated git tag is created, similar to `git tag -am "chore: publish 2.17.1+6.9.1 release" 2.17.1+6.9.1`
+- commit and tag are pushed to the Wordpress recipe repository
 
 !!! warning "Here be more SSH dragons"
 
     In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
 
-Here is the output:
+`abra` recipe publishing command have been designed to complement a semi-automatic workflow. If `abra` breaks or doesn't understand what is going on, you can always finish the process manually with a few Git commands and a bit of luck. We designed `abra` to support this way due to the chaotic nature of container publishing versioning schemes.
 
-```
-WARN[0000] discovered 1.1.0+5.9.0 as currently synced recipe label
-WARN[0000] previous git tags detected, assuming this is a new semver release
-? current: 1.0.2+5.8.3, new: 1.1.0+5.9.0, correct? Yes
-new release published: https://git.coopcloud.tech/coop-cloud/wordpress/src/tag/1.1.0+5.9.0
-```
+If you do this process manually, two important things to note for the release to be picked up in the catalogue:
 
-And once more, we can validate this tag has been created with `cd ~/.abra/recipes/wordpress && git tag -l`.
+- create an annotated git tag using `git tag -a`
+- push the tag with `git push --tags`
 
 ## How are new recipe versions tested?
 
 This is currently a manual process. Our best estimates are to do a backup and run a test deployment and see how things go. [We are working on improving this](https://git.coopcloud.tech/toolshed/-/projects/31).
 
-Following the [entry above](/maintainers/handbook/#how-do-i-release-a-new-recipe-version), before running `abra recipe release --publish <recipe>`, you can deploy the new version of the recipe. You find an app that relies on this recipe and pass `-C/--chaos` to `ugrade` so that it accepts the locally unstaged changes.
+Following the [entry above](/maintainers/handbook/#how-do-i-release-a-new-recipe-version), before running `abra recipe release <recipe>`, you can deploy the new version of the recipe. You find an app that relies on this recipe and pass `-C/--chaos` to `deploy` so that it accepts the locally unstaged changes.
 
 !!! warning "Here be more SSH dragons"
 
@@ -386,6 +499,19 @@ It is good practice to take note of all the issues you ran into and share them w
 
 If you don't have time or are not an operator, reach out on our communication channels for an operator willing to do some testing.
 
+## What does "only updates to Labels are allowed" mean
+
+If you see something like this:
+
+```
+FATA failed to update config traefik_traefik_yml_v22: Error response from daemon: rpc error: code = InvalidArgument desc = only updates to Labels are allowed
+```
+
+It means that a Docker "config" has been updated, but the version number has not been incremented.
+
+To fix this, edit a recipe's `abra.sh` and update the version number of the relevant line –­in this case, `export TRAEFIK_YML_VERSION=v22`.
+`
+
 ## How do I write version release notes?
 
 In the root of your recipe repository, run the following (if the folder doesn't already exist):
@@ -394,13 +520,11 @@ In the root of your recipe repository, run the following (if the folder doesn't
 mkdir -p release
 ```
 
-And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
+And then create or append to the text file `release/next`. This file will be used when running `abra recipe release`. Abra will ask you to use these when running `abra recipe release` and rename it to the release tag, e.g. `release/1.1.0+5.9.0`.
 
-You can also add release notes for the next release into a special file `release/next`. This file will be used when running `abra recipe release`.
+You can also enter the release notes interactively when running `abra recipe release`.
 
-!!! warning "Watch out for old versions of `abra` 🚧"
-
-    This feature is only available in the > 0.9.x series of `abra`.
+`abra` will show these notes when another operator runs `abra app deploy` / `abra app upgrade`.
 
 ## How do I know whether to accept version upgrades when running `abra recipe upgrade <something>`?
 
@@ -476,6 +600,18 @@ If you want to get the highest rating on SSL certs, you can use the following tr
 
 See [this PR](https://git.coopcloud.tech/coop-cloud/traefik/pulls/8/files) for the technical details
 
+## How do I skip secret generation for a specific secret
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.11.x series of `abra`.
+
+Add the `# generate=false` comment
+
+```
+SECRET_JWT_SECRET_VERSION=v1 # generate=false
+```
+
 ## How do I change secret generation length?
 
 It is possible to tell `abra` which length it should generate secrets with from your recipe config.
@@ -497,6 +633,13 @@ of passwords which admins have to type out in database shells.
 
 ## How do I change secret generation characters?
 
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.10.x series of `abra`. 
+    The generation of `hex` secrets is only available in the >= 0.12.x series of `abra`.
+    The generation of `bytes` secrets is only available in the >= 0.13.x series of `abra`.
+
+
 It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
 
 You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
@@ -517,10 +660,52 @@ The possible Values are:
 | `default,special`                            | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and special characters              |
 | `default,safespecial`                        | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#%^&*_-+=`  | Uses uppercase letters, lowercase letters and numbers and console safe special characters |
 | `default`                                    | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789`             | Uses uppercase letters, lowercase letters and numbers                                     |
+| `hex`                                        | `0123456789abcdef`                                                      | Uses only hexadecimal characters (0-9, a-f)                                                |
+| `bytes`                                      | N/A (generates random bytes)                                            | Generates random bytes instead of character-based passwords (requires `length` modifier, automatically uses `encoding=base64`) |
 | any other value or not setting one will be treated as `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789`             | Uses uppercase letters, lowercase letters and numbers                                     |
 
 The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length.
 
+## How do I encode generated secrets?
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.13.x series of `abra`.
+
+You can tell `abra` to encode generated secrets using the `encoding` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
+
+Here is an example:
+
+```bash
+SECRET_API_KEY_VERSION=v1 # length=32 encoding=base64
+```
+
+This will generate a 32-character secret and then base64-encode it before storing.
+
+Currently supported encoding options:
+
+- `base64`: Base64-encodes the generated secret value
+
+**Note:** When using `charset=bytes`, the encoding automatically defaults to `base64` even if not explicitly specified, as raw binary data needs to be encoded for safe storage.
+
+## How do I add a prefix to generated secrets?
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the >= 0.13.x series of `abra`.
+
+You can tell `abra` to add a prefix to generated secrets using the `prefix` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
+
+Here is an example:
+
+```bash
+SECRET_APP_KEY_VERSION=v1 # length=32 charset=bytes prefix=base64:
+```
+
+This will generate a 32-byte random key, base64-encode it, and prefix it with `base64:`. This is useful for applications like Laravel that expect secrets in a specific format.
+
+The prefix is applied after any encoding transformations.
+
 ## How do I configure backup/restore?
 
 From the perspective of the recipe maintainer, backup/restore is just more
@@ -646,10 +831,10 @@ Please note:
 1. The `file_env` / `_FILE` hack is to pass secrets into the container runtime without exposing them in plaintext in the configuration. See [this entry](/maintainers/handbook/#exposing-secrets) for more.
 
 1. In order to pass execution back to the original entrypoint, it's a good idea to find the original entrypoint script and run it from your own entrypoint script. If there is none, you may want to reference the `CMD` definition or if that isn't working, try to actually specify `cmd: ...` in the `compose.yml` definition (there are other recipes which do this).
-  
+
 1. Also it might be necessary to define command: although there is an original entrypoint. That's [due to the fact](https://docs.docker.com/reference/compose-file/services/#entrypoint) that if entrypoint is non-null, Compose ignores any default command from the image, for example the `CMD` instruction in the Dockerfile.
 
-  1. Pratically you would e.g. look for the Dockerfile of the upstream image. In there you should find the docker-entrypoint.sh (or similar) and where it's located. Furthermore you find the `CMD`-line there. 
+  1. Pratically you would e.g. look for the Dockerfile of the upstream image. In there you should find the docker-entrypoint.sh (or similar) and where it's located. Furthermore you find the `CMD`-line there.
   1. Just put in your entrypoint.sh in the last line: exec /path/to/docker-entrypoint.sh "@" (path and filename you should find in upstream Dockerfile) and insert  command:  to your service in compose.yml with the value of what you find in the CMD line of the Dockerfile.
 
 1. If you're feeling reckless, you can also use the Golang templating engine to do things conditionally.

docs/maintainers/index.md

@@ -2,16 +2,28 @@
 title: Maintainers
 ---
 
-Welcome to the maintainers guide! Maintainers are typically individuals who have a stake in building up and maintaining our digital configuration commons, the recipe configurations. Maintainers help keep recipes configurations up to date, respond to issues in a timely manner, help new users within the community and recruit new maintainers when possible.
+Welcome to the recipe maintainers guide! Recipe maintainers help build up and maintain our recipe configuration commons based on [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/).
 
 <div class="grid cards" markdown>
 
-- __New Maintainers Tutorial__
+- __How to Become a Recipe Maintainer™__
 
-    If you want to package a recipe and/or become a maintainer, start here :rocket:
+    If you want to become a recipe maintainer, start here :heart:
+
+    [Learn more](/maintainers/maintain){ .md-button .md-button--primary }
+
+- __Package your First Recipe Tutorial__
+
+    If you want to package a recipe, start here :rocket:
 
     [Get Started](/maintainers/tutorial){ .md-button .md-button--primary }
 
+- __How to Upgrade a Recipe__
+
+    If you want to upgrade a recipe, start here 🤸‍♀️
+
+    [Start upgrading](/maintainers/upgrade){ .md-button .md-button--primary }
+
 - __Packaging Handbook__
 
     One-stop shop for all you need to know to package recipes :package:

docs/maintainers/maintain.md

@@ -0,0 +1,82 @@
+---
+title: How to Become a Recipe Maintainer
+---
+
+!!! warning
+
+    This guide is a work-in-progress following [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/) and the work to to implement this in [`#60`](https://git.coopcloud.tech/coop-cloud/traefik/issues/60) for the [traefik recipe](https://git.coopcloud.tech/coop-cloud/traefik). Please help us update this documentation with new conventions and practices that emerge.
+
+## What does a recipe maintainer do?
+
+A recipe maintainer takes care of one or more recipes. This includes reviewing issues and pull requests and applying application upgrades which are published upstream. The general expectations for what a recipe maintainer should carry out are defined in [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/).
+
+If recipes are maintained by several maintainers, there is a greater chance of stability for all operators who deploy those recipe upgrades for end-users. Please consider becoming a maintainer for recipes which you rely on!
+
+!!! note "We need More Recipe Maintainers!"
+
+    Since the publishing of [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/) there is a growing consensus that it is critically important that we recruit more recipe maintainers. The recipe configuration commons on its own is not enough. We also need to coordinate our maintenance work to ensure that everyone can benefit from smooth and stable upgrades.
+
+## You can become a recipe maintainer!
+
+Anyone who deploys a recipe can become a recipe maintainer. If you want to ensure that a recipe becomes stable and reliable, then you can become the maintainer. If you maintain a recipe alone, ask for help and encourage others to join in. The only way we can reduce the endless workload of application updates is to coordinate our work together.
+
+### `README.md` and `MAINTENANCE.md`
+
+You can start by reading The Maintainers Proposal: [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/). Check if there are maintainers mentioned in the `README.md` of the recipe repository and if there is a `MAINTENANCE.md` present. For example, for the traefik recipe, here is [the list of maintainers in the `README.md`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/8eaee04b5d9980a99fdad57677a4c72d7796da10/README.md?display=source#L8) and the maintainers guidelines in the [`MAINTENANCE.md`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/8eaee04b5d9980a99fdad57677a4c72d7796da10/MAINTENANCE.md). If there is no `MAINTENANCE.md`, copy the template below and create your own.
+
+### Maintainers Team
+
+It is important that only recipe maintainers have write permissions to the repository. As it currently stands, every member of the [Co-operators Team](https://git.coopcloud.tech/org/coop-cloud/teams/co-operators) has write permissions to all recipe repositories for convenience while we are missing enough maintainers.
+
+To change this, create a new team on [`git.coopcloud.tech/coop-cloud/teams`](https://git.coopcloud.tech/org/coop-cloud/teams) for your specific recipe, e.g. `mycoolrecipe-maintainers`. Add yourself and any other maintainers and don't forget to add the recipe repository itself on the repositories tab. Remove your recipe repository from the [list of repositories for the Co-operators Team](https://git.coopcloud.tech/org/coop-cloud/teams/co-operators/repositories) so that write permissions are removed.
+
+### Repository Permissions
+
+Under `Branch Protection` in the recipe repository settings, create a new rule
+for the `main` / `master` branch of your repository. Add your maintainer team
+to the following list of permissions.
+
+* Allow only maintainers to push directly to the main branch
+    * `Allowlist Restricted Push` > `Allowlisted teams for pushing`
+* Allow only maintainers to approve pull requests
+    * `Restrict approvals to allowlisted users or teams` > `Allowlisted teams for reviews`
+* Allow only maintainers to merge pull requests
+    * `Enable Merge Allowlist` > `Allowlisted  teams for merging`
+
+## Templates
+
+### `MAINTENANCE.md` template
+
+!!! warning
+
+    We are still considering if it is a good idea to create a `MAINTENANCE.md`
+    for every recipe repository. Maybe it is a better idea to make a single
+    `MAINTENANCE.md` on [docs.coopcloud.tech](https://docs.coopcloud.tech). We
+    look forward to seeing feedback on this from new maintainers.
+
+See the [`MAINTENANCE.md`](https://git.coopcloud.tech/coop-cloud/traefik/raw/branch/master/MAINTENANCE.md) of the Traefik recipe.
+
+### Pull request template
+
+See the [`.gitea/PULL_REQUEST_TEMPLATE.md`](https://git.coopcloud.tech/coop-cloud/traefik/src/branch/master/.gitea/PULL_REQUEST_TEMPLATE.md) of the Traefik recipe.
+
+
+## Where can maintainers find support?
+
+### Chat
+
+An active community exists in the [`#coopcloud-tech`](https://matrix.to/#/#coopcloud-tech:autonomic.zone?via=autonomic.zone) channel, which can answer your questions and help with issues. Please be patient when asking for support.
+
+### Recipe Issue Tracker
+
+If you're stuck on a problem, create an issue in your recipe's issue tracker. Users of your repository may contribute PRs, otherwise you can ask the community for support.
+
+### Toolshed
+
+If you're blocked by a problem in Coop Cloud's tooling, write a ticket to one of the [Toolshed](https://git.coopcloud.tech/toolshed) issue trackers. For example:
+
+* [abra](https://git.coopcloud.tech/toolshed/abra/issues)
+* [docs.coopcloud.tech](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/issues)
+* [recipes.coopcloud.tech](https://git.coopcloud.tech/toolshed/recipes.coopcloud.tech/issues)
+
+If you cannot find a repository to match your problem, you can write in the [organizing issues](https://git.coopcloud.tech/toolshed/organising/issues) tracker. (See: [migration notice](https://git.coopcloud.tech/toolshed/organising/issues/667))

docs/maintainers/tutorial.md

@@ -50,7 +50,7 @@ Open the `compose.yml` in your favourite editor and have a gander 🦢. The
 5. The MariaDB service doesn't need to be exposed to the internet, so we can define an `internal` network for it to communicate with Matomo.
 6. Lastly, we want to use `deploy.labels` and remove the `ports:` definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
 
-The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
+The resulting `compose.yml` is available [here](https://git.coopcloud.tech/coop-cloud/matomo/src/branch/main/compose.yml).
 
 ### Updating the `.env.sample`
 
@@ -87,7 +87,7 @@ Otherwise, or once you've done that, go ahead and deploy the app:
 abra app deploy swarm.example.com
 ```
 
-Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables, if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
+Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables, if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.coopcloud.tech/coop-cloud/mediawiki) for examples of both).
 
 ### Finishing up
 

docs/maintainers/upgrade.md

@@ -0,0 +1,15 @@
+---
+title: How to Upgrade a Recipe
+---
+
+## Updating versions in the `abra.sh`
+
+`#TODO`
+
+## Backwards compatible environment variable changes
+
+`#TODO`
+
+## Creating new release notes
+
+`#TODO`

docs/operators/handbook.md

@@ -94,11 +94,31 @@ git commit
 make link
 ```
 
+## Configure `abra` with `abra.yml`
+
+There are few configuration options supported at this time but more can be added. We are open to requests!
+
+### `$ABRA_DIR`
+
+The lookup logic is defined like so.
+
+* lookup $ABRA_DIR env
+* look for config file and take value from there
+* $HOME/.abra as fallback
+
+If you create an `abra.yml` file in your `$PWD` with the following contents.
+
+```
+abraDir: .
+```
+
+Then `$ABRA_DIR` will be automatically picked up as `$PWD`. This is useful when you maintain multiple project configurations and recipes in various state of chaos and would like to separate those. `abra` will create all the usual `$HOME/.abra` state (`servers`/`recipes`/etc.) under your chosen `abraDir` value. This allows you to have multiple independent versions of specific recipes which are relevant for specific projects vs. relying on a single `$ABRA_DIR/recipes/<recipe>` and constantly having to switch between different chaotic hacks.
+
 ## Running abra server side
 
-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 work station.
+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
@@ -106,7 +126,7 @@ abra server add --local
 
 !!! note "Technical details"
 
-	This will tell `abra` to look at the Docker system running on the server, instead of a remote one (using the Docker internal `default` context). Once this is wired up, `abra` knows that the deployment target is the local server and not a remote one. This will be handle seamlessly for all other deployments on this server.
+	This will tell `abra` to look at the Docker system running on the server itself, instead of a remote one (using the Docker internal `default` context). Once this is wired up, `abra` knows that the deployment target is the local server and not a remote one. This will be handled seamlessly for all other deployments on this server.
 
 Make sure to back up your `~/.abra` directory on the server, or put it in version control, as well as other files you'd like to keep safe.
 
@@ -300,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`:
@@ -464,10 +514,16 @@ route requests after. You're free to make as many `$whatever.yml` files in your
 Yes, it's possible although currently Quite Experimental! See
 [`#388`](https://git.coopcloud.tech/toolshed/organising/issues/388) for more.
 
+## Can I deploy images from a private registry?
+
+Yes, as of [`#585`](https://git.coopcloud.tech/toolshed/abra/pulls/585), this is possible. At current time of writing, this feature is unreleased but this will change shortly. You need to run `docker login` before you run your deploy command.
+
 ## Running an offline coop-cloud server 
 
 You may want to run a coop-cloud directly on your device (or in a VM or machine on your LAN), whether that's for testing a recipe or to run coop-cloud apps outside of the cloud ;-)
-In that case you might simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
+
+In that case you might set up your server with `abra add server --local` like you would do it [running abra server side](#running-abra-server-side) (without a specific server name).
+Then you could simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`, `127.0.0.1 coopcloud.local`, `127.0.0.1 *.coopcloud.local`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
 1. In your traefik .env file, edit/uncomment the following lines:
 ```
 LETS_ENCRYPT_ENV=staging
@@ -476,7 +532,8 @@ SECRET_WILDCARD_CERT_VERSION=v1
 SECRET_WILDCARD_KEY_VERSION=v1
 COMPOSE_FILE="$COMPOSE_FILE:compose.wildcard.yml"
 ```
-2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`
+2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`. You can also use wildcard-subdomains if you want to be more flexible later one, which apps to deploy: `subjectAltName=DNS:coopcloud.local,DNS:*.coopcloud.local`. 
+
 3. Run these commands:
 ```
 abra app secret insert localhost ssl_cert v1 localhost.crt -f
@@ -488,7 +545,7 @@ abra app secret insert localhost ssl_key v1 localhost.key -f
 
 !!! warning "Watch out for old versions of `abra` 🚧"
 
-    This feature is only available in the > 0.10.x series of `abra`.
+    This feature is only available in the >= 0.10.x series of `abra`.
 
 It is possible to specify a remote recipe in your `.env` file:
 
@@ -508,7 +565,7 @@ $ABRA_DIR/recipes/mygit_org_myorg_cool-recipe
 
 !!! warning "Watch out for old versions of `abra` 🚧"
 
-    This feature is only available in the > 0.10.x series of `abra`.
+    This feature is only available in the >= 0.10.x series of `abra`.
 
 If you `abra app new`/`abra app deploy`/`abra app upgrade`/`abra app rollback`,
 the version that is deployed will be written to your app `.env` file. You can
@@ -529,13 +586,13 @@ TYPE=custom-html:1.7.1+1.27.2
 
 This `.env` version is then used as the recipe checkout version for **all**
 `abra` operations afterwards unless you specify otherwise on the command-line
-with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
+with `[version]` `--chaos/-C` or `--latest/-l`.
 
 ## How is the new deployment version determined?
 
 !!! warning "Watch out for old versions of `abra` 🚧"
 
-    This feature is only available in the > 0.10.x series of `abra`.
+    This feature is only available in the >= 0.10.x series of `abra`.
 
 ### `.env` version
 
@@ -545,7 +602,7 @@ deployment overview.
 
 This `.env` version is then used as the recipe checkout version for **all**
 `abra` operations afterwards unless you specify otherwise on the command-line
-with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
+with `[version]` `--chaos/-C` or `--latest/-l`.
 
 ### `abra app deploy`
 
@@ -568,7 +625,7 @@ The version is chosen using the following priority logic.
 1. deployed app
 1. recipe catalogue (if undeployed)
 
-Use `--ignore-env-version/-i` to deploy the latest release version or commit.
+Use `--latest/-l` to deploy the latest release version or commit.
 
 In all cases 3-5, the app `.env` version is **ignored** as a version candidate.
 

docs/operators/tutorial.md

@@ -13,60 +13,58 @@ In order to deploy an app you need two things:
 
 This tutorial tries to help you make choices about which server and which DNS setup you need to run a _Co-op Cloud_ deployment but it does not go into great depth about how to set up a new server.
 
-### Server setup
+We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html).
 
-Co-op Cloud has itself near zero system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
+### Server provisioning
 
-We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html). You may also be interested in this [FAQ entry](/intro/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.
+Co-op Cloud is designed to run on a variety of hardware, so you can use those single-board computers, old laptops/desktops, or refurbished servers. However, hardware setup is a skill that's beyond the scope of this guide. As long as it's running Linux and has networking, it should be fine! Most Co-op Cloud deployments have been run on Debian machines so far.
 
-Most Co-op Cloud deployments have been run on Debian machines so far. Some experiments have been done on single board computers & servers with low resource capacities.
+If you don't have the time or equipment to run your own hardware, rented hardware is fine too! There are many hosting providers which will provide a Linux server to you for a monthly fee.
 
-You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy ([Traefik](https://traefik.io)) keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.
+### Server configuration
 
-`abra` has support for creating servers (`abra server new`) but that is a more advanced automation feature which is covered in the [handbook](/operators/handbook). For this tutorial, we'll focus on the basics. Assuming you've managed to create a testing VPS with some `$hosting_provider`, you'll need to install Docker, add your user to the Docker group & setup swarm mode:
+Assuming you've got a running server, it's now time to configure it.
 
-!!! warning "You may need to log in/out"
+Co-op Cloud has very few system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
 
-    When running `usermod ...`, you may need to (depending on your system) log
-    in and out again of your shell session to get the required permissions for
-    Docker.
-    Alternatively you can run [`newgrp`](https://www.man7.org/linux/man-pages/man1/newgrp.1.html) to register the group chnage.
+To get started, you'll need to install Docker, add your user to the Docker group & setup swarm mode. Many hosting providers support [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html), which allows you to automate the steps in this section. If that applies to you, you can use [our cloud-init file](https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/cloud-init/cloud-init.yaml).
+
+Otherwise, here are the step required:
 
 ```
 # ssh into your server
 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
+
+# now setup swarm
+sudo docker swarm init
+sudo docker network create -d overlay proxy
+```
+
+#### Using docker without sudo
+
+Abra can't deploy any applications in future steps unless it can run `docker` commands without sudo.
+
+```
 # check if the docker group exists
 groups | grep docker
 
 # if the docker group doesn't already exist, add it manually
-sudo groupadd docker
+groupadd docker
 
 # add user to docker group
 sudo usermod -aG docker $USER
-
-# check that docker installed correctly
-docker run hello-world
-
-# exit and re-login to load the group
-exit
-ssh <server-domain>
-
-# back on the server, setup swarm
-docker swarm init
-docker network create -d overlay proxy
-
-# now you can exit and start using abra
-exit
 ```
-Abra can't deploy any applications in future steps if the docker group cannot run without sudo. If you install docker a different way, it may not create a docker group automatically. The [official Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/) can help if you run into further issues.
 
-??? question "Do you support multiple web proxies?"
+After running `usermod`, you may need to (depending on your system) log out (`exit`) and back in again (`ssh <server-domain>`) to get the required permissions for Docker before proceeding.
 
-    We do not know if it is feasible and convenient to set things up on an existing server with another web proxy which uses ports `:80` & `:443`. We'd happily receive reports and documentation on how to do this if you manage to set it up!
+The [official Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/) can help if you run into further issues.
 
 ### DNS setup
 
@@ -79,16 +77,21 @@ Your entries in your DNS provider setup might look like the following.
 
 Where `116.203.211.204` can be replaced with the IP address of your server.
 
-Warning: If the you are in the same local netwrok as the server, you might run into [NAT Hairpin](https://superuser.com/questions/663820/port-forwarding-from-inner-network-to-inner-network-hairpin-nat) issues.
+!!! warning Beware local network pitfalls!
+
+    If you are in the same local network as the server, you might run into [NAT Hairpin](https://superuser.com/questions/663820/port-forwarding-from-inner-network-to-inner-network-hairpin-nat) issues.
 
 ??? question "How do I know my DNS is working?"
 
     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)):
+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)):
 
 ```bash
 curl https://install.abra.coopcloud.tech | bash
@@ -112,7 +115,7 @@ you have immediate access to `abra` on the current terminal.
 export PATH=$PATH:$HOME/.local/bin
 ```
 
-If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/toolshed/organising/issues/new) :pray:
+If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/toolshed/abra/issues/new) :pray:
 
 ??? question "Can I install `abra` on my server?"
 
@@ -126,7 +129,7 @@ With autocomplete enabled, you can run a command like `abra app deploy myapp.exa
 
 ### Add your server
 
-Now you can connect `abra` with your server. You must have a working SSH configuration for your server before you can proceed. That means you can run `ssh <server-domain>` on your command-line and everything Works :tm:. See the [`abra` SSH troubleshooting](/abra/trouble/#ssh-connection-issues) for a working SSH configuration example.
+Now you can connect `abra` with your server. You must have a working SSH configuration for your server before you can proceed. That means you can run `ssh <server-domain>` on your command-line and everything Works :tm:. See the [`abra` SSH troubleshooting](/abra/trouble/#ssh-connection-issues) for a working SSH configuration example or use `abra server add -h` for the help output.
 
 ??? warning "Beware of SSH dragons :dragon_face:"
 
@@ -140,21 +143,21 @@ Now you can connect `abra` with your server. You must have a working SSH configu
     troubleshooting entry](/abra/trouble/#ssh-connection-issues).
 
 ```bash
-ssh <server-domain> # make sure it works
+ssh <server-domain> hostname -I # make sure it works
 abra server add <server-domain>
 ```
 
-It is important to note that `<server-domain>` here is a publicy accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting.
+It is important to note that `<server-domain>` here is a publicly accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting.
 
 ??? warning "Can I use arbitrary server names?"
 
-    Yes, this is possible. You need to pass `-D` to `server add` and ensure
-    that your `Host ...` entry in your SSH configuration includes the name.
-    So, for example, in `~/.ssh/config`:
+    Yes, this is possible. You need to ensure that your `Host ...` entry in your SSH configuration includes the name.  So, for example, in `~/.ssh/config`:
+
     ```
       Host example.com example
         ...
     ```
+
     And then:
 
       abra server add example
@@ -169,8 +172,9 @@ abra server ls
 
 ??? question "How do I share my configs in `~/.abra`?"
 
-    It's possible and quite easy, for more see [this handbook
+    It's possible and relatively easy, for more see [this handbook
     entry](/operators/handbook/#understanding-app-and-server-configuration).
+    [Git](https://git-scm.com) skills are generally required.
 
 ### Web proxy setup
 
@@ -180,6 +184,13 @@ Traefik is the main entrypoint for all web requests (e.g. like NGINX) and
 supports automatic SSL certificate configuration and other quality-of-life
 features which make deploying libre apps more enjoyable.
 
+You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.
+
+??? question "Do you support multiple web proxies?"
+
+    Yes, this is possible. See [this handbook entry](/operators/handbook/#proxying-apps-outside-of-co-op-cloud-with-traefik)
+    for more. Be warned, this is a relatively advanced topic.
+
 **1. To get started, you'll need to create a new app:**
 
 ```bash
@@ -187,8 +198,10 @@ abra app new traefik
 ```
 
 Choose your newly registered server and specify a domain name. By default `abra`
-will suggest `<app-name>.server.org` or prompt you with a list of servers.
+will suggest `<app-name>.<your-server>` or prompt you with a list of servers.
 
+??? question "Should I use www for traefik?"
+    Generally no. No one will be directly accessing the traefik domain name unless they want to see the traefik dashboard. You should reserve the `www` or apex domains for apps like [custom-html](https://recipes.coopcloud.tech/custom-html-tiny) which let you host sites. Traefik is just a proxy to other apps!
 
 **2. Configure this new `traefix` app**
 
@@ -217,8 +230,6 @@ DASHBOARD_ENABLED=false
 
 **3. Now it is time to deploy your app:**
 
-Ensure `<traefic-domain>` is registered in `/etc/hosts` then run:
-
 ```
 abra app deploy <traefik-domain>
 ```
@@ -231,7 +242,7 @@ Voila. Abracadabra :magic_wand: your first app is deployed :sparkles:
 And now we can deploy apps. Let's create a new Nextcloud app.
 
 ```bash
-abra app new nextcloud -S
+abra app new nextcloud --secrets
 ```
 
 The `-S` or `--secrets` flag is used to generate secrets for the app: database connection password, root password and admin password.
@@ -240,7 +251,7 @@ The `-S` or `--secrets` flag is used to generate secrets for the app: database c
 
     Take care, these secrets are only shown once on the terminal so make sure to take note of them! `abra` makes use of the [Docker secrets](/operators/handbook/#managing-secret-data) mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in `/run/secrets` on the container file system.
 
-Make sure` <nextcloud-domain>` is registered in `/etc/hosts`, then we can deploy Nextcloud:
+Now we can deploy Nextcloud:
 
 ```bash
 abra app deploy <nextcloud-domain>
@@ -251,10 +262,9 @@ abra app deploy <nextcloud-domain>
 ```
 abra app ps -w <nextcloud-domain>     # status check
 abra app logs <nextcloud-domain>      # logs trailing
-abra app errors -w <nextcloud-domain> # error catcher
 ```
 
-Your new `traefik` instance will detect that a new app is coming up and generate SSL certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<netcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
+Your new `traefik` instance will detect that a new app is coming up and generate TLS certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<nextcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
 
 ### Upgrade Nextcloud
 
@@ -264,35 +274,6 @@ To upgrade an app manually to the newest available version run:
 abra app upgrade <nextcloud-domain>
 ```
 
-### Automatic Upgrades
-
-`kadabra` the auto-updater is still under development, use it with care and don't use it in production environments. To setup the auto-updater copy the `kadabra` binary to the server and configure a cronjob for regular app upgrades. The following script will configure ssmtp for email notifications and setup a cronjob. This cronjob checks daily for new app versions, notifies if any kind of update is available and upgrades all apps to the latest patch/minor version.
-
-
-```bash
-apt install ssmtp
-
-cat > /etc/ssmtp/ssmtp.conf << EOF
-mailhub=$MAIL_SERVER:587
-hostname=$MAIL_DOMAIN
-AuthUser=$USER
-AuthPass=$PASSWORD
-FromLineOverride=yes
-UseSTARTTLS=yes
-EOF
-
-cat > /etc/cron.d/abra_updater << EOF
-MAILTO=admin@example.com
-MAILFROM=noreply@example.com
-
-0  6 * * *       root    ~/kadabra notify --major
-30 4 * * *       root    ~/kadabra upgrade --all
-EOF
-
-```
-
-Add `ENABLE_AUTO_UPDATE=true` to the env config (`abra app config <app name>`) to enable the auto-updater for a specific app.
-
 ## Finishing up
 
 Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.

mkdocs.yml

@@ -84,15 +84,19 @@ nav:
       - federation/index.md
       - federation/handbook.md
       - federation/organisers.md
+      - federation/kite-flying-pad-archive.md
       - "Bylaws": federation/bylaws.md
       - "Finance": federation/finance.md
       - "Membership": federation/membership.md
       - "Code of Co-operation": federation/code-of-coop.md
+      - "Shared Infrastructure Inventory": federation/infra.md
       - "Proposals":
         - federation/proposals/index.md
         - federation/proposals/federation.md
       - "Resolutions":
           - federation/resolutions/index.md
+          - "Draft":
+              - federation/resolutions/index.md
           - "Passed":
               - federation/resolutions/passed/001.md
               - federation/resolutions/passed/002.md
@@ -122,19 +126,26 @@ nav:
               - federation/resolutions/passed/027.md
               - federation/resolutions/passed/028.md
               - federation/resolutions/passed/029.md
+              - federation/resolutions/passed/032.md
+              - federation/resolutions/passed/031.md
+              - federation/resolutions/passed/033.md
+              - federation/resolutions/passed/034.md
+              - federation/resolutions/passed/036.md
           - "Stalled":
               - federation/resolutions/stalled/013.md
+              - federation/resolutions/stalled/030.md
           - "In Progress":
               - federation/resolutions/index.md
-              - federation/resolutions/in-progress/030-docs-naming-survey.md
-              - federation/resolutions/in-progress/031.md
+              - federation/resolutions/in-progress/035.md
+              - federation/resolutions/in-progress/037.md
       - "Minutes":
           - federation/minutes/index.md
           - "Recently":
+              - federation/minutes/2025-12-28.md
+          - "Archive":
               - federation/minutes/2024-08-15.md
               - federation/minutes/2024-04-17.md
               - federation/minutes/2024-03-29.md
-          - "Archive":
               - federation/minutes/2024-02-01.md
               - federation/minutes/2022-03-03.md
               - federation/minutes/2023-05-03.md
@@ -156,6 +167,7 @@ nav:
       - "Hack": abra/hack.md
       - "Troubleshoot": abra/trouble.md
       - "Cheat Sheet": abra/cheat-sheet.md
+      - "Swarm mode almanac": abra/swarm.md
   - "Specifications":
       - specs/index.md
       - "Backups":

requirements.txt

@@ -1,6 +1,6 @@
 mkdocs~=1.6.1
 
-mkdocs-material==9.5.49
+mkdocs-material==9.6.20
 mkdocs-material-extensions==1.3.1
 mkdocs-awesome-pages-plugin==2.10.1
 pygments==2.19.1