From 844a5835dad990706391d6ee25be6628177c06f1 Mon Sep 17 00:00:00 2001 From: decentral1se Date: Wed, 18 Mar 2026 09:24:43 +0100 Subject: [PATCH 01/14] 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 Date: Sat, 21 Mar 2026 17:23:52 +0100 Subject: [PATCH 02/14] 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 Date: Sat, 21 Mar 2026 17:27:34 +0100 Subject: [PATCH 03/14] 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 Date: Sat, 21 Mar 2026 17:29:43 +0100 Subject: [PATCH 04/14] 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 Date: Sat, 21 Mar 2026 17:31:03 +0100 Subject: [PATCH 05/14] 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 Date: Sat, 21 Mar 2026 18:01:04 +0100 Subject: [PATCH 06/14] 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 Date: Sat, 21 Mar 2026 18:05:35 +0100 Subject: [PATCH 07/14] 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 Date: Sat, 21 Mar 2026 18:40:19 +0100 Subject: [PATCH 08/14] 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 Date: Sat, 21 Mar 2026 18:43:04 +0100 Subject: [PATCH 09/14] 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 Date: Mon, 23 Mar 2026 12:48:53 +0100 Subject: [PATCH 10/14] 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 Date: Sun, 4 Jan 2026 22:29:23 +0000 Subject: [PATCH 11/14] 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/` 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 Date: Sun, 22 Mar 2026 01:51:44 +0100 Subject: [PATCH 12/14] 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 Date: Mon, 23 Mar 2026 13:13:09 +0100 Subject: [PATCH 13/14] 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= docker system prune --all --force` if you have multiple docker contexts). From cf251b3b2573b48e14feb011b29982cbb94253ba Mon Sep 17 00:00:00 2001 From: decentral1se Date: Tue, 24 Mar 2026 07:52:14 +0100 Subject: [PATCH 14/14] 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.