From 807370bdd77463cb62612f0d4727120fd1794140 Mon Sep 17 00:00:00 2001
From: mayel <git@mayel.space>
Date: Wed, 1 Oct 2025 15:33:34 +0000
Subject: [PATCH 01/39] add sudo in front of `group add`

otherwise fails in some scenarios
---
 docs/operators/tutorial.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md
index 5b071a3..db2288a 100644
--- a/docs/operators/tutorial.md
+++ b/docs/operators/tutorial.md
@@ -55,7 +55,7 @@ Abra can't deploy any applications in future steps unless it can run `docker` co
 groups | grep docker
 
 # if the docker group doesn't already exist, add it manually
-groupadd docker
+sudo groupadd docker
 
 # add user to docker group
 sudo usermod -aG docker $USER

From aa756e69a5b1075531971134b2167bbe021651a6 Mon Sep 17 00:00:00 2001
From: ammaratef45 <ammaratef45@proton.me>
Date: Tue, 17 Mar 2026 07:32:27 +0000
Subject: [PATCH 02/39] Update docs/federation/membership.md

---
 docs/federation/membership.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation/membership.md b/docs/federation/membership.md
index 7cf0813..d3fbeb3 100644
--- a/docs/federation/membership.md
+++ b/docs/federation/membership.md
@@ -21,4 +21,4 @@ title: Membership
 | [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` |
-| [Merri-bek tech]( ammaratef45@proton.me ) | - | - | `coop-cloud-delegate@merri-bek.tech`|
+| [Merri-bek tech](https://www.merri-bek.tech/) | - | - | `coop-cloud-delegate@merri-bek.tech`|

From dc53c48f4324c95ea82fe0f20a71a502c42378bd Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 17 Mar 2026 09:05:43 +0100
Subject: [PATCH 03/39] feat: how to join

---
 docs/federation/index.md |  6 +++---
 docs/federation/join.md  | 21 +++++++++++++++++++++
 2 files changed, 24 insertions(+), 3 deletions(-)
 create mode 100644 docs/federation/join.md

diff --git a/docs/federation/index.md b/docs/federation/index.md
index 40c0502..c6ef4ea 100644
--- a/docs/federation/index.md
+++ b/docs/federation/index.md
@@ -26,11 +26,11 @@ This is the public facing page where we publish all things federation in the ope
 
     [Our Members](/federation/membership){ .md-button .md-button--primary }
 
-- __Minutes__
+- __Join the Federation__
 
-    All minutes from our meetings 📒
+    How to join the Federation 📒
 
-    [Past Meetings](/federation/minutes){ .md-button .md-button--primary }
+    [Join us](/federation/join){ .md-button .md-button--primary }
 
 - __Digital Tools__
 
diff --git a/docs/federation/join.md b/docs/federation/join.md
new file mode 100644
index 0000000..4531de9
--- /dev/null
+++ b/docs/federation/join.md
@@ -0,0 +1,21 @@
+---
+title: Joining the Co-op Cloud Federation (CCF)
+---
+
+Organisations that are aligned with our values can apply to join CCF.
+
+Read more about [membership benefits](/federation/proposals/federation/#benefits) and [responsibilities](/proposals/federation/#responsibilities).
+
+## How to join
+
+1. Learn about Co-op Cloud and the Federation if you haven’t already: [The Co-op Cloud Federation Proposal](/federation/proposals/federation/#overview)
+1. Consider joining one of our “Kite Flying” regular online gatherings to introduce yourself and your organisation. You can [get in touch](/intro/contact) and/or check our [fediverse account](https://social.coop/@coopcloud) for announcements on the time/date for the upcoming Kite-Flying.
+1. If you know someone who is already a member, ask them if they will be willing to vouch for you joining the CCF. We will ask them to submit the proposal for your joining.
+1. Email us at `helo@coopcloud.tech`, providing the following information as the basis for a proposal:
+    * Name of organisation.
+    * Summary (2 sentence overview of your orgnisation and why you wish to be a member)
+    * Details (further details regarding your use of Co-op Cloud software, and existing or planned involvement in the organisation.
+    * Name of your sponsor, if any
+    * Representative name.
+    * Matrix contact / email address.
+1. The other members of CCF will vote on the proposal for your organisation to join; you should hear from us within 2 weeks. We will ask you for a Matrix contact to include on our published list of member organisations.

From 12c496d6f7c22e273fbd4cf5f78fe5f782584fc2 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 17 Mar 2026 09:05:50 +0100
Subject: [PATCH 04/39] refactor!: indicate where to search

---
 docs/federation/resolutions/index.md | 21 +--------------------
 1 file changed, 1 insertion(+), 20 deletions(-)

diff --git a/docs/federation/resolutions/index.md b/docs/federation/resolutions/index.md
index 8a19987..223474c 100644
--- a/docs/federation/resolutions/index.md
+++ b/docs/federation/resolutions/index.md
@@ -2,23 +2,4 @@
 title: Resolutions
 ---
 
-### Resolution Template
-
-``` yaml
----
-title: Resolution <number>
----
-
-- Topic: <title>
-- Date: 13-12-2023
-- Deadline: Date
-- Size: large or medium
-
-## Summary
-
-Who this affects, and what it does...
-
-## Details
-
-A narrative with details...
-```
+On the left-hand sidebar, you can view all draft/in-progress/passed and stalled resolutions.

From 2aae23e966e537acda6aa75d666dbd7b80526905 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 17 Mar 2026 09:10:35 +0100
Subject: [PATCH 05/39] fix: drop "-"

---
 docs/federation/join.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation/join.md b/docs/federation/join.md
index 4531de9..c5e8eb6 100644
--- a/docs/federation/join.md
+++ b/docs/federation/join.md
@@ -9,7 +9,7 @@ Read more about [membership benefits](/federation/proposals/federation/#benefits
 ## How to join
 
 1. Learn about Co-op Cloud and the Federation if you haven’t already: [The Co-op Cloud Federation Proposal](/federation/proposals/federation/#overview)
-1. Consider joining one of our “Kite Flying” regular online gatherings to introduce yourself and your organisation. You can [get in touch](/intro/contact) and/or check our [fediverse account](https://social.coop/@coopcloud) for announcements on the time/date for the upcoming Kite-Flying.
+1. Consider joining one of our “Kite Flying” regular online gatherings to introduce yourself and your organisation. You can [get in touch](/intro/contact) and/or check our [fediverse account](https://social.coop/@coopcloud) for announcements on the time/date for the upcoming Kite Flying.
 1. If you know someone who is already a member, ask them if they will be willing to vouch for you joining the CCF. We will ask them to submit the proposal for your joining.
 1. Email us at `helo@coopcloud.tech`, providing the following information as the basis for a proposal:
     * Name of organisation.

From 0cd2c23c8c95b769227596e66da4717b69a03138 Mon Sep 17 00:00:00 2001
From: stevensting <stefan@klasse-methode.it>
Date: Tue, 17 Mar 2026 10:10:47 +0100
Subject: [PATCH 06/39] add/modify some links regarding the joining process

---
 docs/federation/join.md       | 2 +-
 docs/federation/membership.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/federation/join.md b/docs/federation/join.md
index c5e8eb6..ce9b762 100644
--- a/docs/federation/join.md
+++ b/docs/federation/join.md
@@ -2,7 +2,7 @@
 title: Joining the Co-op Cloud Federation (CCF)
 ---
 
-Organisations that are aligned with our values can apply to join CCF.
+Organisations that are aligned with our [idea](/federation/proposals/federation/), [values](/federation/code-of-coop/) and [bylaws](/federation/bylaws/) can apply to join CCF.
 
 Read more about [membership benefits](/federation/proposals/federation/#benefits) and [responsibilities](/proposals/federation/#responsibilities).
 
diff --git a/docs/federation/membership.md b/docs/federation/membership.md
index d3fbeb3..d21cfcb 100644
--- a/docs/federation/membership.md
+++ b/docs/federation/membership.md
@@ -2,7 +2,7 @@
 title: Membership
 ---
 
-> Are you also interested in joining the federation? Please see [Resolution 002](/federation/resolutions/passed/002/) for our process on how to join. If you have any questions, [drop us a line](/intro/contact/) with us for a chat
+> Are you also interested in joining the federation? Please check [our process](/federation/join/) on how to join. If you have any questions, [drop us a line](/intro/contact/) or come for a chat.
 
 | Name      | Dues Paid | Notes    | Contact |
 | --------- | --------- | -------- |-------- |

From 4f24035ea56587b56291eab96c0919e42c2dd79c Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 17 Mar 2026 11:26:21 +0100
Subject: [PATCH 07/39] fix: feedback

---
 docs/federation/join.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/federation/join.md b/docs/federation/join.md
index c5e8eb6..2c39bef 100644
--- a/docs/federation/join.md
+++ b/docs/federation/join.md
@@ -2,9 +2,9 @@
 title: Joining the Co-op Cloud Federation (CCF)
 ---
 
-Organisations that are aligned with our values can apply to join CCF.
+Organisations that are aligned with our values (e.g. [vision](/proposals/federation/#vision), [strategy](/intro/strategy/), [code of co-operation](/federation/code-of-coop/)) can apply to join CCF.
 
-Read more about [membership benefits](/federation/proposals/federation/#benefits) and [responsibilities](/proposals/federation/#responsibilities).
+Read more about [membership benefits](/proposals/federation/#benefits) and [responsibilities](/proposals/federation/#responsibilities).
 
 ## How to join
 

From 762736ff7d4496116def41ab89b68b670a59c06b Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 17 Mar 2026 11:31:18 +0100
Subject: [PATCH 08/39] fix: ugh, links

---
 docs/federation/join.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/federation/join.md b/docs/federation/join.md
index 2c39bef..315fe26 100644
--- a/docs/federation/join.md
+++ b/docs/federation/join.md
@@ -2,9 +2,9 @@
 title: Joining the Co-op Cloud Federation (CCF)
 ---
 
-Organisations that are aligned with our values (e.g. [vision](/proposals/federation/#vision), [strategy](/intro/strategy/), [code of co-operation](/federation/code-of-coop/)) can apply to join CCF.
+Organisations that are aligned with our values (e.g. [vision](/federation/proposals/federation/#vision), [strategy](/intro/strategy/), [code of co-operation](/federation/code-of-coop/)) can apply to join CCF.
 
-Read more about [membership benefits](/proposals/federation/#benefits) and [responsibilities](/proposals/federation/#responsibilities).
+Read more about [membership benefits](/federation/proposals/federation/#benefits) and [responsibilities](/federation/proposals/federation/#responsibilities).
 
 ## How to join
 

From d700b9468c80211ee700a98192262fbfc49b77b0 Mon Sep 17 00:00:00 2001
From: stevensting <stefan@klasse-methode.it>
Date: Tue, 17 Mar 2026 12:54:38 +0100
Subject: [PATCH 09/39] another linkt ot the application process

---
 docs/federation/bylaws.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation/bylaws.md b/docs/federation/bylaws.md
index f16b8ee..fda88b1 100644
--- a/docs/federation/bylaws.md
+++ b/docs/federation/bylaws.md
@@ -28,4 +28,4 @@ According to [Resolution 002](/federation/resolutions/passed/002):
 
 > To join the federation an existing member must create a large decision to approve of the new member (paid or solidarity).
 
-So, please [get in touch](/intro/contact) if you'd like to join!
+So, please [read up here](/federation/join/) about the application process.

From 844a5835dad990706391d6ee25be6628177c06f1 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Wed, 18 Mar 2026 09:24:43 +0100
Subject: [PATCH 10/39] fix: add to menu

---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index 1dedf65..cd4a327 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -88,6 +88,7 @@ nav:
       - "Bylaws": federation/bylaws.md
       - "Finance": federation/finance.md
       - "Membership": federation/membership.md
+      - "Joining the Co-op Cloud Federation": federation/join.md
       - "Code of Co-operation": federation/code-of-coop.md
       - "Shared Infrastructure Inventory": federation/infra.md
       - "Proposals":

From 137e45b08df3e846e57f41c35519705ab77f5e69 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 17:23:52 +0100
Subject: [PATCH 11/39] feat: finally write those upgrade docs

---
 docs/maintainers/upgrade.md | 70 +++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md
index 845e0db..c3af4e4 100644
--- a/docs/maintainers/upgrade.md
+++ b/docs/maintainers/upgrade.md
@@ -2,14 +2,78 @@
 title: How to Upgrade a Recipe
 ---
 
+!!! warning "The recipe config commons is people!"
+
+    This documentation is all about helping you make recipe configuration
+    changes that won't break other peoples upgrade deployments :heart: There
+    are some specific maintainer responsibilities which are not exactly
+    obvious. This page is all about making them simple and clear to understand.
+    We hope it's clear and if not, please send documentation patches!
+
 ## Updating versions in the `abra.sh`
 
-`#TODO`
+If you update a config in a recipe, you also need to update the associated config version.
+
+For example, in the [Traefik](https://git.coopcloud.tech/coop-cloud/traefik)
+recipe, we have the following in
+[`compose.yml`](https://git.coopcloud.tech/coop-cloud/traefik/src/branch/master/compose.yml#L104-L108):
+
+```yaml
+configs:
+  traefik_yml:
+    name: ${STACK_NAME}_traefik_yml_${TRAEFIK_YML_VERSION}
+    file: traefik.yml.tmpl
+    template_driver: golang
+```
+And in the [`abra.sh`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/9a46c85735701780dc8f0717a4e6cab4969420fc/abra.sh#L1), we have:
+
+```bash
+export TRAEFIK_YML_VERSION=v29
+```
+
+If you update teh `traefik.yml.tmpl` with new changes, you **must** increment
+`TRAEFIK_YML_VERSION`. Otherwise, other Co-op Cloud operators will see an
+obscure error message when they try to deploy your new version.
 
 ## Backwards compatible environment variable changes
 
-`#TODO`
+If you add a new environment variable to the `.env.sample` then you create
+manual upgrade work for other Co-op Cloud operators. Depending on the
+functionality that the environment variable enables or how the recipe is
+already configured, it is possible to provide a default which maintains
+backwards compatibility. There is hard and fast rule for this and it depends on
+the recipe and context.
+
+A typical way to do this, is to provide a default in the `environment` stanza.
+For example, providing a default of `false` for `NEW_ENV_VARS` so Co-op Cloud
+operators do not need to set `NEW_ENV_VAR=false` in their app `.env` file.
+
+```yaml
+environment:
+    - NEW_ENV_VAR=${NEW_ENV_VAR:-false}
+```
+
+Sometimes it is not appropriate to provide a default and it is important that
+other Co-op Cloud operators make an informed choice about the setting of an
+environment variable. In this case, please consider leaving a note about your
+new environment variables in the release notes (see below). The release of this
+change should then be considered a break change and require a major release
+version.
+
+`abra` will also warn Co-op Cloud operators about missing environment variables
+that are present in the recipe `.env.sample` but not in their app `.env` file.
 
 ## Creating new release notes
 
-`#TODO`
+Help other Co-op Cloud operators understand what they need to take care of when
+doing an upgrade deployment by creating some [release
+notes](/maintainers/handbook/#how-do-i-write-version-release-notes) about your
+specific changes.
+
+This is crucial when there are breaking changes, data migrations, work-arounds,
+hacks etc. present in the new changes. `abra` will show what you write when
+others run `abra app upgrade`.
+
+Good release notes are proven to save hours of pain and misery, so put
+solidarity into practice and write some excellent release notes for your fellow
+Co-op Cloud operators!

From db8c54bd11f81eb71c89ff72574a3d660656ee8f Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 17:27:34 +0100
Subject: [PATCH 12/39] fix: also provide contact deets

---
 docs/maintainers/upgrade.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md
index c3af4e4..2fabd6c 100644
--- a/docs/maintainers/upgrade.md
+++ b/docs/maintainers/upgrade.md
@@ -8,7 +8,8 @@ title: How to Upgrade a Recipe
     changes that won't break other peoples upgrade deployments :heart: There
     are some specific maintainer responsibilities which are not exactly
     obvious. This page is all about making them simple and clear to understand.
-    We hope it's clear and if not, please send documentation patches!
+    We hope it's clear and if not, please send documentation patches and/or
+    [get in touch](/intro/contact)!
 
 ## Updating versions in the `abra.sh`
 

From 99bc41a621a2e392899c587f81cb9cbdfea6dc3f Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 17:29:43 +0100
Subject: [PATCH 13/39] fix: wording, typos

---
 docs/maintainers/upgrade.md | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md
index 2fabd6c..85385ff 100644
--- a/docs/maintainers/upgrade.md
+++ b/docs/maintainers/upgrade.md
@@ -32,22 +32,24 @@ And in the [`abra.sh`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/
 export TRAEFIK_YML_VERSION=v29
 ```
 
-If you update teh `traefik.yml.tmpl` with new changes, you **must** increment
+If you update the `traefik.yml.tmpl` with new changes, you **must** increment
 `TRAEFIK_YML_VERSION`. Otherwise, other Co-op Cloud operators will see an
 obscure error message when they try to deploy your new version.
 
 ## Backwards compatible environment variable changes
 
-If you add a new environment variable to the `.env.sample` then you create
-manual upgrade work for other Co-op Cloud operators. Depending on the
-functionality that the environment variable enables or how the recipe is
-already configured, it is possible to provide a default which maintains
-backwards compatibility. There is hard and fast rule for this and it depends on
-the recipe and context.
+If you add a new environment variable to the `.env.sample` then you can
+potentially create manual upgrade work for other Co-op Cloud operators.
+
+Depending on the functionality that the environment variable enables or how the
+recipe is already configured, it is possible to provide a default which
+maintains backwards compatibility. There is no hard and fast rule for this and it
+depends on the recipe and context.
 
 A typical way to do this, is to provide a default in the `environment` stanza.
-For example, providing a default of `false` for `NEW_ENV_VARS` so Co-op Cloud
-operators do not need to set `NEW_ENV_VAR=false` in their app `.env` file.
+For example, providing a default of `false` for a new fictitous environment
+variable called `NEW_ENV_VAR` so other Co-op Cloud operators do not need to set
+`NEW_ENV_VAR=false` in their app `.env` file (unless they want to change it).
 
 ```yaml
 environment:

From 1f5a90694bebb728346fe2e5291052d1ceb1e160 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 17:31:03 +0100
Subject: [PATCH 14/39] fix: wording

---
 docs/maintainers/upgrade.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md
index 85385ff..4133790 100644
--- a/docs/maintainers/upgrade.md
+++ b/docs/maintainers/upgrade.md
@@ -60,7 +60,7 @@ Sometimes it is not appropriate to provide a default and it is important that
 other Co-op Cloud operators make an informed choice about the setting of an
 environment variable. In this case, please consider leaving a note about your
 new environment variables in the release notes (see below). The release of this
-change should then be considered a break change and require a major release
+change should then be considered a breaking change and require a major release
 version.
 
 `abra` will also warn Co-op Cloud operators about missing environment variables

From fd98c6f19c35e821f0b955ef8a7a1461e1a76f5f Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 18:01:04 +0100
Subject: [PATCH 15/39] fix: show sidebar

---
 mkdocs.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index cd4a327..ef599e3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -73,7 +73,9 @@ nav:
       - "Support Us": intro/support.md
   - "Maintainers":
       - maintainers/index.md
-      - "New Maintainers Tutorial": maintainers/tutorial.md
+      - "How to Become a Recipe Maintainer": maintainers/maintain.md
+      - "Package your First Recipe Tutorial": maintainers/tutorial.md
+      - "How to Upgrade a Recipe": maintainers/upgrade.md
       - "Packaging Handbook": maintainers/handbook.md
       - maintainers/catalogue.md
   - "Operators":

From 5f7f2214b57aa9e2afafc061bff2f6a41c3a6a12 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 18:05:35 +0100
Subject: [PATCH 16/39] fix: remove double title

---
 docs/maintainers/tutorial.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/maintainers/tutorial.md b/docs/maintainers/tutorial.md
index 6facefc..ea2a837 100644
--- a/docs/maintainers/tutorial.md
+++ b/docs/maintainers/tutorial.md
@@ -1,9 +1,7 @@
 ---
-title: New maintainers tutorial
+title: Package your First Recipe Tutorial
 ---
 
-## Package your first recipe
-
 ### Overview
 
 Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn them, there is nothing more to learn. It can seem daunting at first but it's simple and easy to do once you know the tricks.

From 7d7ffeda93d8e3f6d83f748134a3875675b97421 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 18:40:19 +0100
Subject: [PATCH 17/39] fix: wording

---
 docs/maintainers/upgrade.md | 2 +-
 mkdocs.yml                  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md
index 4133790..a5cf480 100644
--- a/docs/maintainers/upgrade.md
+++ b/docs/maintainers/upgrade.md
@@ -1,5 +1,5 @@
 ---
-title: How to Upgrade a Recipe
+title: Recipe config upgrade checklist
 ---
 
 !!! warning "The recipe config commons is people!"
diff --git a/mkdocs.yml b/mkdocs.yml
index ef599e3..959d333 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -75,7 +75,7 @@ nav:
       - maintainers/index.md
       - "How to Become a Recipe Maintainer": maintainers/maintain.md
       - "Package your First Recipe Tutorial": maintainers/tutorial.md
-      - "How to Upgrade a Recipe": maintainers/upgrade.md
+      - "Recipe config upgrade checklist": maintainers/upgrade.md
       - "Packaging Handbook": maintainers/handbook.md
       - maintainers/catalogue.md
   - "Operators":

From 3112d4d9e5caf2f77e9b618c14f67d0fff7c1c68 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Sat, 21 Mar 2026 18:43:04 +0100
Subject: [PATCH 18/39] fix: also wording

---
 docs/maintainers/index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/maintainers/index.md b/docs/maintainers/index.md
index 7f0b68a..0862a54 100644
--- a/docs/maintainers/index.md
+++ b/docs/maintainers/index.md
@@ -18,9 +18,9 @@ Welcome to the recipe maintainers guide! Recipe maintainers help build up and ma
 
     [Get Started](/maintainers/tutorial){ .md-button .md-button--primary }
 
-- __How to Upgrade a Recipe__
+- __Recipe config upgrade checklist__
 
-    If you want to upgrade a recipe, start here 🤸‍♀️
+    If you want to upgrade a recipe config, please make sure you take these steps into consideration 🤸‍♀️
 
     [Start upgrading](/maintainers/upgrade){ .md-button .md-button--primary }
 

From 2f2ff65fe95cd96199938a41bd6dedacfd4f8bbe Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Mon, 23 Mar 2026 12:48:53 +0100
Subject: [PATCH 19/39] feat: HOWTO backwards compat in tmpl files

---
 docs/maintainers/upgrade.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/maintainers/upgrade.md b/docs/maintainers/upgrade.md
index a5cf480..7f3d869 100644
--- a/docs/maintainers/upgrade.md
+++ b/docs/maintainers/upgrade.md
@@ -56,6 +56,14 @@ environment:
     - NEW_ENV_VAR=${NEW_ENV_VAR:-false}
 ```
 
+Another approach is to set this default within the configuration where you
+reference the environment variable. In `.tmpl` files, this generally works out
+something like this:
+
+```
+my_config_option = {{ or (env "NEW_ENV_VAR") "false" }}
+```
+
 Sometimes it is not appropriate to provide a default and it is important that
 other Co-op Cloud operators make an informed choice about the setting of an
 environment variable. In this case, please consider leaving a note about your

From 805dcae97282f3d99c0bfb7af638b7189749c1f9 Mon Sep 17 00:00:00 2001
From: jeppebundsgaard <jeppe@bundsgaard.net>
Date: Sun, 4 Jan 2026 22:29:23 +0000
Subject: [PATCH 20/39] Added some info about editor as config setting

---
 docs/operators/handbook.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md
index 5d4a75b..211dc0e 100644
--- a/docs/operators/handbook.md
+++ b/docs/operators/handbook.md
@@ -96,6 +96,8 @@ make link
 
 ## Configure `abra` with `abra.yml`
 
+You can place an `abra.yml`-file in the root of your .abra-project.
+
 There are few configuration options supported at this time but more can be added. We are open to requests!
 
 ### `$ABRA_DIR`
@@ -106,7 +108,7 @@ The lookup logic is defined like so.
 * 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.
+If you create an `abra.yml` file in your `$PWD` (print working directory) with the following contents.
 
 ```
 abraDir: .
@@ -114,6 +116,12 @@ 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.
 
+### `$EDITOR`
+
+When you edit .env.sample-files, you are asked to chose an editor. To avoid answering that question all the time, you can either set an environment variable (`export EDITOR=nano`), or you can set it as a config-option in abra.yml, like this:
+
+`editor: nano`
+
 ## 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 computer.

From 72137b9bdc16ba65966f40112ec1ccff8dc45234 Mon Sep 17 00:00:00 2001
From: Jeppe Bundsgaard <jeppe@bundsgaard.net>
Date: Sun, 22 Mar 2026 01:51:44 +0100
Subject: [PATCH 21/39] info about cleaning up the server

---
 docs/operators/handbook.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md
index 211dc0e..0541441 100644
--- a/docs/operators/handbook.md
+++ b/docs/operators/handbook.md
@@ -695,3 +695,13 @@ present.
 
 However, it is otherwise **ignored** for the version candidate. The "source of
 truth" for the version candidate is the live deployment of the app.
+
+### Clean up the server
+
+When you have deployed and undeployed apps, or when you have updated apps, docker will not automatically remove the images and containers. At some point your disk will be full, and you get strange errors when trying to deploy new apps. 
+
+Log into your server with `ssh`. 
+
+You can view all information about containers and images using the command `docker system df -v`. You might see images used by 0 containers and DEAD and exited containers. 
+
+If you are *completely* SURE that you have deployed all the apps, you want to keep, you can remove all dead and unused images and containers with the command `docker system prune --all --force` (or `DOCKER_CONTEXT=foo docker system prune --all --force` if you have multiple docker contexts).

From 947c62501ed4838ca0db8185aff090106f8baa14 Mon Sep 17 00:00:00 2001
From: Jeppe Bundsgaard <jeppe@bundsgaard.net>
Date: Mon, 23 Mar 2026 13:13:09 +0100
Subject: [PATCH 22/39] minor changes

---
 docs/operators/handbook.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md
index 0541441..ade94ae 100644
--- a/docs/operators/handbook.md
+++ b/docs/operators/handbook.md
@@ -96,7 +96,7 @@ make link
 
 ## Configure `abra` with `abra.yml`
 
-You can place an `abra.yml`-file in the root of your .abra-project.
+You can place an `abra.yml`-file in the root of your `$ABRA_DIR`.
 
 There are few configuration options supported at this time but more can be added. We are open to requests!
 
@@ -118,7 +118,7 @@ Then `$ABRA_DIR` will be automatically picked up as `$PWD`. This is useful when
 
 ### `$EDITOR`
 
-When you edit .env.sample-files, you are asked to chose an editor. To avoid answering that question all the time, you can either set an environment variable (`export EDITOR=nano`), or you can set it as a config-option in abra.yml, like this:
+When you edit `.env.sample` files, you are asked to chose an editor. To avoid answering that question all the time, you can either set an environment variable (`export EDITOR=nano`), or you can set it as a config-option in abra.yml, like this:
 
 `editor: nano`
 
@@ -704,4 +704,4 @@ Log into your server with `ssh`.
 
 You can view all information about containers and images using the command `docker system df -v`. You might see images used by 0 containers and DEAD and exited containers. 
 
-If you are *completely* SURE that you have deployed all the apps, you want to keep, you can remove all dead and unused images and containers with the command `docker system prune --all --force` (or `DOCKER_CONTEXT=foo docker system prune --all --force` if you have multiple docker contexts).
+If you are *completely* SURE that you have deployed all the apps, you want to keep, you can remove all dead and unused images and containers with the command `docker system prune --all --force` (or `DOCKER_CONTEXT=<server-domain> docker system prune --all --force` if you have multiple docker contexts).

From cf251b3b2573b48e14feb011b29982cbb94253ba Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 24 Mar 2026 07:52:14 +0100
Subject: [PATCH 23/39] refactor: wrap, links, formatting

---
 docs/federation/resolutions/passed/038.md | 30 +++++++++++++++++------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/docs/federation/resolutions/passed/038.md b/docs/federation/resolutions/passed/038.md
index 7d1cf54..26f9a0f 100644
--- a/docs/federation/resolutions/passed/038.md
+++ b/docs/federation/resolutions/passed/038.md
@@ -9,21 +9,35 @@ title: "Resolution 038: Merri-bek Tech joins Co-op Cloud Federation"
 
 ### Summary
 
-Merri-bek Tech is working towards neighbourhood-first, community controlled web services, building infrastructure using  the Co-op Cloud stack. Merri-bek Tech expects to pay membership dues.
+[Merri-bek Tech](https://www.merri-bek.tech) is working towards
+neighbourhood-first, community controlled web services, building infrastructure
+using  the Co-op Cloud stack. Merri-bek Tech expects to pay membership dues.
 
 ### Details
 
 Merri-bek Tech
 
 - currently depends on Traefik for neighbourhood-distributed nodes.
-- have developed and are maintaining Kiwix Co-op Cloud recipe for deploying Wikipedia across neighbourhood nodes
-- plans to use and contribute to maintenance, of additional components of Co-op Cloud stack as needed for subsequent phases of the project roadmap: neighbhourhood based email service, web hosting and decentralized social media.
+- have developed and are maintaining Kiwix Co-op Cloud recipe for deploying
+  Wikipedia across neighbourhood nodes
+- plans to use and contribute to maintenance, of additional components of Co-op
+  Cloud stack as needed for subsequent phases of the project roadmap:
+  neighbhourhood based email service, web hosting and decentralized social
+  media.
 
-@jade:merri-bek.chat is an active member of the Co-op Cloud community.
-The group is based in Merri-bek, in the inner Northern suburbs of Naarm (Melbourne), Australia
+`@jade:merri-bek.chat` is an active member of the Co-op Cloud community. The
+group is based in Merri-bek, in the inner Northern suburbs of Naarm
+(Melbourne), Australia
 
-[Merri-bek Tech Inc.] is legally an incorporated association in Australia, which is a legal entity used for democratic clubs and societies. It is not intended to be a worker co-operative, it is a volunteer commons project, but it shares the mutuality goals of cooperatives. Full details are at [merri-bek.tech](https://merri-bek.tech).
+`[Merri-bek Tech Inc.]` is legally an incorporated association in Australia,
+which is a legal entity used for democratic clubs and societies. It is not
+intended to be a worker co-operative, it is a volunteer commons project, but it
+shares the mutuality goals of cooperatives. Full details are at
+[merri-bek.tech](https://merri-bek.tech).
 
-The project that Merri-bek Tech is running to promote Neighbourhood-First Software in Merri-bek and other regions, is detailed at [lores.tech](https://lores.tech).
+The project that Merri-bek Tech is running to promote Neighbourhood-First
+Software in Merri-bek and other regions, is detailed at
+[lores.tech](https://lores.tech).
 
-@ammaratef45 from RTM is honored to vouch
\ No newline at end of file
+`@ammaratef45` from [RTM](https://resisttechmonopolies.online/) is honored to
+vouch.

From b44e944924bbcc4943b26bd308b48b99318eff25 Mon Sep 17 00:00:00 2001
From: stevensting <stefan@klasse-methode.it>
Date: Tue, 24 Mar 2026 10:53:00 +0100
Subject: [PATCH 24/39] remove outdated autocompletion setup

---
 docs/abra/cheat-sheet.md | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/docs/abra/cheat-sheet.md b/docs/abra/cheat-sheet.md
index 5ad5baf..14ca388 100644
--- a/docs/abra/cheat-sheet.md
+++ b/docs/abra/cheat-sheet.md
@@ -8,18 +8,6 @@ title: Cheat sheet
     not all flags are listed here.
 
 
-### Abra Autocomplete
-
-Definitely set up autocomplete or you'll be sad :sob: `abra` supports `bash`,
-`zsh`, and `fizsh` just run
-
-```
-$ abra autocomplete bash
-# Restart your terminal or load autocompletion in place
-$ source /etc/bash_completion.d/abra
-```
-
-
 ### Create & deploy an app
 
 ```

From b883e574c7910cce92f39f9727b99f4fe796a14b Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Fri, 27 Mar 2026 14:38:20 +0100
Subject: [PATCH 25/39] docs: moar rant

---
 docs/abra/swarm.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/abra/swarm.md b/docs/abra/swarm.md
index 0045533..1bc137b 100644
--- a/docs/abra/swarm.md
+++ b/docs/abra/swarm.md
@@ -52,4 +52,4 @@ In practice, this is what we currently rely on Swarm mode for.
 
 * 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.
+* 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. This means we have a "one by one" deployment model which would respect `depends_on` and have explicit way to configure roll backs (instead of it happening whenever Swarm feels like it). 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.

From 45b9d1ad6df09fccb630f0ad28c8bb86727868c3 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Fri, 27 Mar 2026 14:39:07 +0100
Subject: [PATCH 26/39] fix: wording

---
 docs/abra/swarm.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/abra/swarm.md b/docs/abra/swarm.md
index 1bc137b..252107c 100644
--- a/docs/abra/swarm.md
+++ b/docs/abra/swarm.md
@@ -52,4 +52,4 @@ In practice, this is what we currently rely on Swarm mode for.
 
 * 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. This means we have a "one by one" deployment model which would respect `depends_on` and have explicit way to configure roll backs (instead of it happening whenever Swarm feels like it). 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.
+* 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. This means we have a "one by one" deployment model which would respect `depends_on` and have explicit way to configure rollbacks (instead of it happening whenever Swarm feels like it). 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.

From 59fec5dfb9484d32c48524a4ca99c29c7cad4ac1 Mon Sep 17 00:00:00 2001
From: p4u1 <p4u1_f4u1@riseup.net>
Date: Fri, 27 Mar 2026 18:38:11 +0000
Subject: [PATCH 27/39] A note on quality and trust (#310)

open to any suggestions :)

Reviewed-on: https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/pulls/310
Reviewed-by: decentral1se <decentral1se@noreply.git.coopcloud.tech>
Reviewed-by: ammaratef45 <ammaratef45@proton.me>
Co-authored-by: p4u1 <p4u1_f4u1@riseup.net>
Co-committed-by: p4u1 <p4u1_f4u1@riseup.net>
---
 docs/maintainers/maintain.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/maintainers/maintain.md b/docs/maintainers/maintain.md
index ddb2822..94eada5 100644
--- a/docs/maintainers/maintain.md
+++ b/docs/maintainers/maintain.md
@@ -20,6 +20,10 @@ If recipes are maintained by several maintainers, there is a greater chance of s
 
 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.
 
+!!! note "A note on quality and trust!"
+
+    The real promise of [`R025`](https://docs.coopcloud.tech/federation/resolutions/passed/025/) is that a single person or collective does not need to maintain every recipe they deploy. This way we can focus on few recipes where we can put our efforts and expertise instead of trying to keep up with updates from half of the recipe catalogue. This is all due to the trust we put in our fellow maintainer comrades and backed by our [democratic federation](https://docs.coopcloud.tech/federation).
+
 ### `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.

From cd06ece0b520b88a8f83d990bcad5675ccbd613a Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Fri, 3 Apr 2026 18:08:56 +0200
Subject: [PATCH 28/39] docs: more swarm considerations + layout

---
 docs/abra/swarm.md | 48 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 13 deletions(-)

diff --git a/docs/abra/swarm.md b/docs/abra/swarm.md
index 252107c..09686ca 100644
--- a/docs/abra/swarm.md
+++ b/docs/abra/swarm.md
@@ -2,8 +2,28 @@
 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.
+!!! 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.
+
+!!! note "No Rug Pull Guarantee :tm:"
+    If we do decide to change, we need a solution 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.
+
+    No changes will happen without democratic decision making and a solution
+    which does not leave anyone behind. It might be that we keep using Swarm
+    for decades to come. There is no need to worry and no rugs will be pulled.
+    Please get involved in the discussion to provide your input.
+
 
 ## Support matrix
 
@@ -16,11 +36,15 @@ In practice, this is what we currently rely on Swarm mode for.
 | 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
+## *Maybe* unsupport matrix
+
+In practice, we don't see people in our community using Swarm mode for this.
+Please report in on `#coop-cloud-tech-future-brain:autonomic.zone` if you do
+use it! We could really use your input.
 
 | 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. |
+| Multi-node | It is possible but it doesn't seem like anyone in our community is really doing this? Please report in to `#coop-cloud-tech-future-brain:autonomic.zone` to discuss your usage if you are using multi-node swarm! 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 [a bunch](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. |
 
 ## Limitations
 
@@ -36,15 +60,7 @@ In practice, this is what we currently rely on Swarm mode for.
 
 * 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.
+## What we seem to need
 
 * 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.
 
@@ -53,3 +69,9 @@ In practice, this is what we currently rely on Swarm mode for.
 * 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. This means we have a "one by one" deployment model which would respect `depends_on` and have explicit way to configure rollbacks (instead of it happening whenever Swarm feels like it). 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.
+
+## 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.

From ca4fc920fdca7bf6d63ebbee1d46f8e063a55c16 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Fri, 3 Apr 2026 18:18:19 +0200
Subject: [PATCH 29/39] docs: room and further explanation

---
 docs/abra/swarm.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/abra/swarm.md b/docs/abra/swarm.md
index 09686ca..54e8a93 100644
--- a/docs/abra/swarm.md
+++ b/docs/abra/swarm.md
@@ -6,9 +6,9 @@ title: Swarm mode almanac
     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.
+    this page as you see fit! The goal of this page is to understand what Swarm
+    offers us, what it's good and bad at, what it doesn't do and what are some
+    alternatives we might consider. In short, we're still researching.
 
 !!! note "No Rug Pull Guarantee :tm:"
     If we do decide to change, we need a solution that is backwards compatible
@@ -22,7 +22,8 @@ title: Swarm mode almanac
     No changes will happen without democratic decision making and a solution
     which does not leave anyone behind. It might be that we keep using Swarm
     for decades to come. There is no need to worry and no rugs will be pulled.
-    Please get involved in the discussion to provide your input.
+    Please get involved in the discussion
+    (`#coop-cloud-tech-future-brain:autonomic.zone`) to provide your input.
 
 
 ## Support matrix

From 80e3df79c6cfc930c567dcb5db6fa14569738a20 Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Fri, 3 Apr 2026 19:12:06 +0200
Subject: [PATCH 30/39] docs: bike workshop proposal

---
 docs/intro/faq.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/docs/intro/faq.md b/docs/intro/faq.md
index e26ff09..3eb4ab0 100644
--- a/docs/intro/faq.md
+++ b/docs/intro/faq.md
@@ -39,6 +39,25 @@ We think our carefully chosen blend of technologies and our [social approach](/f
 Please read our [initial project announcement post](https://autonomic.zone/blog/co-op-cloud/) for more on this.
 Also see our [strategy page](../strategy/).
 
+## Should I use Co-op Cloud?
+
+We think we can recommend Co-op Cloud in the same way we can recommend a local
+DIY bike repair workshop instead of a professional bike repair shop.
+
+You go to fix your bike, they maybe have the tool you need, it's usually
+chaotically organised, they ask you basically to do the work yourself and
+*maybe* you manage to fix your bike!
+
+Some times you turn up and it's closed because nobody had energy to open up
+that night or they forgot to update their website with the new schedule.
+
+You generally meet really nice people while trying to figure out how the hell
+you get your new brakes fitted. You definitely feel empowered to improve your
+own bike fixing skills in the future and consider helping others with their
+bike.
+
+Co-op Cloud is basically like a digital DIY bike repair workshop 😛
+
 ## How do I make a recipe for (package) an app?
 
 Head on over to **Maintainers** section and see ["Package your first recipe"](/maintainers/tutorial/#package-your-first-recipe) for more.
@@ -183,7 +202,6 @@ It seems like this recommendation changed by the time Co-op Cloud was initiated:
 > Volumes are the preferred way to persist data in Docker containers and services.<br>
 > — [Docker "Storage" docs](https://docs.docker.com/engine/storage/#good-use-cases-for-volumes)
 
-
 > Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and don't incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting your data even if no running container is using them.<br>
 >  — [Docker OverlayFS docs](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/#use-volumes-for-write-heavy-workloads)
 

From 79bd10ff039f52f68cbfef5092e6b0203c3d9745 Mon Sep 17 00:00:00 2001
From: iexos <hritter@posteo.de>
Date: Fri, 10 Apr 2026 22:35:18 +0200
Subject: [PATCH 31/39] op tutorial: add update check

---
 docs/operators/tutorial.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md
index d4fea9b..a68b50b 100644
--- a/docs/operators/tutorial.md
+++ b/docs/operators/tutorial.md
@@ -266,9 +266,15 @@ abra app logs <nextcloud-domain>      # logs trailing
 
 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
+### Upgrades
 
-To upgrade an app manually to the newest available version run:
+You can check if any of your deployed apps have updates available with:
+
+```bash
+abra app ls -S
+```
+
+To upgrade an app to the newest available version run:
 
 ```bash
 abra app upgrade <nextcloud-domain>

From 40a8d25257128de2a9f283d44d29547b0a00bf28 Mon Sep 17 00:00:00 2001
From: 3wordchant <3wordchant@noreply.git.coopcloud.tech>
Date: Mon, 27 Apr 2026 18:12:07 +0000
Subject: [PATCH 32/39] Add more detail to gitea team setup

---
 docs/maintainers/maintain.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/maintainers/maintain.md b/docs/maintainers/maintain.md
index 94eada5..65c6636 100644
--- a/docs/maintainers/maintain.md
+++ b/docs/maintainers/maintain.md
@@ -32,7 +32,16 @@ You can start by reading The Maintainers Proposal: [`R025`](https://docs.coopclo
 
 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.
+To change this:
+
+1. Log into git.coopcloud.tech as an administrator account (e.g. `coopcloud`)
+2. Create a new team on [`git.coopcloud.tech/coop-cloud/teams`](https://git.coopcloud.tech/org/coop-cloud/teams) with the following settings:
+
+    - Name: e.g. `mycoolrecipe-maintainers`
+    - Repository access: Specific repositories
+    - Permission: Administrator access 
+3. Add maintainers as "Team Members" on the "members" tab, and add the recipe repository on the "repositories" tab 
+3. 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
 

From b3e954c6950d929fb10be0fc1e891e5642edcb77 Mon Sep 17 00:00:00 2001
From: f <f@sutty.nl>
Date: Mon, 27 Apr 2026 12:25:45 -0300
Subject: [PATCH 33/39] fix: resolution 037 has passed

---
 docs/federation/resolutions/{in-progress => passed}/037.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/federation/resolutions/{in-progress => passed}/037.md (100%)

diff --git a/docs/federation/resolutions/in-progress/037.md b/docs/federation/resolutions/passed/037.md
similarity index 100%
rename from docs/federation/resolutions/in-progress/037.md
rename to docs/federation/resolutions/passed/037.md

From 35222964924fe00011398d8c7ab28612a977461e Mon Sep 17 00:00:00 2001
From: f <f@sutty.nl>
Date: Mon, 27 Apr 2026 12:27:29 -0300
Subject: [PATCH 34/39] fix: resolution 035 has passed

---
 docs/federation/resolutions/{in-progress => passed}/035.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/federation/resolutions/{in-progress => passed}/035.md (100%)

diff --git a/docs/federation/resolutions/in-progress/035.md b/docs/federation/resolutions/passed/035.md
similarity index 100%
rename from docs/federation/resolutions/in-progress/035.md
rename to docs/federation/resolutions/passed/035.md

From b6014385fe21570992e842374ac944f70d3f6b6b Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Mon, 27 Apr 2026 21:54:44 +0200
Subject: [PATCH 35/39] fix: mv 35/37 also

---
 mkdocs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 959d333..4aeccbc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -133,15 +133,15 @@ nav:
               - federation/resolutions/passed/031.md
               - federation/resolutions/passed/033.md
               - federation/resolutions/passed/034.md
+              - federation/resolutions/passed/035.md
               - federation/resolutions/passed/036.md
+              - federation/resolutions/passed/037.md
               - federation/resolutions/passed/038.md
           - "Stalled":
               - federation/resolutions/stalled/013.md
               - federation/resolutions/stalled/030.md
           - "In Progress":
               - federation/resolutions/index.md
-              - federation/resolutions/in-progress/035.md
-              - federation/resolutions/in-progress/037.md
       - "Minutes":
           - federation/minutes/index.md
           - "Recently":

From aa553414d766515c6be355024da396ec3597af58 Mon Sep 17 00:00:00 2001
From: mayel <git@mayel.space>
Date: Wed, 6 May 2026 10:07:57 +0000
Subject: [PATCH 36/39] Update docs/federation/membership.md

---
 docs/federation/membership.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation/membership.md b/docs/federation/membership.md
index d21cfcb..8d6926d 100644
--- a/docs/federation/membership.md
+++ b/docs/federation/membership.md
@@ -8,7 +8,7 @@ title: Membership
 | --------- | --------- | -------- |-------- |
 | Agaric    | - | - | `@wolcen:matrix.org` |
 | [Autonomic](https://autonomic.zone) | - | - | `@3wc`, `@cas`, `@knoflook`, `@travvy`, `@aadil` |
-| [Bonfire](https://bonfirenetworks.org) | - | - | `@mayel:matrix.org` + Ivan (`@cambriale:matrix.org`) |
+| [Bonfire](https://bonfirenetworks.org) | ✅ | - | `@mayel:matrix.org` + Ivan (`@cambriale:matrix.org`) |
 | [Doop.coop](https://doop.coop) | - | - | `@yusf:gottsnack.net` |
 | [EOTL](https://eotl.supply) | - | - | `@basebuilder:pub.solar` |
 | [Karrot](https://karrot.world) | - | - | `@nicksellen:matrix.org` |

From adc7a331513f32a3c69e25c3818dc079a7b89ab5 Mon Sep 17 00:00:00 2001
From: mayel <git@mayel.space>
Date: Wed, 6 May 2026 10:13:44 +0000
Subject: [PATCH 37/39] Update docs/federation/kite-flying-pad-archive.md

---
 docs/federation/kite-flying-pad-archive.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/federation/kite-flying-pad-archive.md b/docs/federation/kite-flying-pad-archive.md
index 2ce119f..b8b3851 100644
--- a/docs/federation/kite-flying-pad-archive.md
+++ b/docs/federation/kite-flying-pad-archive.md
@@ -4,6 +4,12 @@ title: Kite Flying "Open Agenda" archive
 
 From https://pad.autonomic.zone/VtyrLUl9RWaJGgEDrncQUw?edit#
 
+## Next kite flying (open community meeting)
+
+[Schedule (ICS link)](https://coopcloud.tech/ics/kite-flying.ics) (subscribe in your calendar app)
+
+---
+
 ## 2026-02-12
 
 Here: p4u1, mo, apfelwurm

From 51e9145b969da88b647f6b4978d3564290874271 Mon Sep 17 00:00:00 2001
From: mayel <git@mayel.space>
Date: Wed, 6 May 2026 10:15:53 +0000
Subject: [PATCH 38/39] Update docs/federation/organisers.md

---
 docs/federation/organisers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation/organisers.md b/docs/federation/organisers.md
index cac00ba..212f620 100644
--- a/docs/federation/organisers.md
+++ b/docs/federation/organisers.md
@@ -26,7 +26,7 @@ We're still working out what it looks like to do this kind of work in the projec
 
 The "Kite Flying Hour" is a weekly public moment where anyone can "drop by" into a Jitsi call and ask/do/propose whatever and meet some people who are currently working on the project. We haven't worked it all out but our process for now is the following.
 
-Someone from Autonomic will volunteer to be present and talk about the project for an hour weekly, alternating between 12 and 19 UTC each week. We announce the hour via our socials: A [pinned toot](https://social.coop/@coopcloud/113555815289767778) on [`@coopcloud@social.coop`](https://social.coop/@coopcloud) and a post to the `#coopcloud:autonomic.zone` room.
+Someone should volunteer to be present and talk about the project for an hour weekly, alternating between 12 and 19 UTC each week. We schedule the call [in a shared calendar](https://coopcloud.tech/ics/kite-flying.ics) (which people can subscribe to in calendar apps) and announce the hour via our socials: A pinned toot on [`@coopcloud@social.coop`](https://social.coop/@coopcloud) and a post to the `#coopcloud:autonomic.zone` room.
 
 Here is some invitation boilerplate which you can use:
 

From 1f0fb6d68a15b2be802d61372dde82e14c905fc0 Mon Sep 17 00:00:00 2001
From: decentral1se <decentral1se@noreply.git.coopcloud.tech>
Date: Fri, 15 May 2026 08:51:59 +0000
Subject: [PATCH 39/39] docs: status

---
 docs/federation/funding-applications/ford-foundation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation/funding-applications/ford-foundation.md b/docs/federation/funding-applications/ford-foundation.md
index 38c0168..6a50c14 100644
--- a/docs/federation/funding-applications/ford-foundation.md
+++ b/docs/federation/funding-applications/ford-foundation.md
@@ -4,7 +4,7 @@ title: Ford foundation
 
 # Ford foundation
 
-> Status: **pending**
+> Status: **rejected**
 
 * [Previous material](https://notes.bonfire.cafe/nlnet-bonfire-coopcloud-hosting)
 * [Application](https://fordfoundation.forms.fm/2023-digital-infrastructure-insights-fund-rfp/forms/9724)