fix: resolution 035 has passed

open to any suggestions :)

Reviewed-on: toolshed/docs.coopcloud.tech#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/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
 
 ```

docs/abra/swarm.md

@@ -2,8 +2,29 @@
 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! 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
+    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
+    (`#coop-cloud-tech-future-brain:autonomic.zone`) to provide your input.
+
 
 ## Support matrix
 
@@ -16,11 +37,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 +61,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.
 
@@ -52,4 +69,10 @@ 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 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.

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
+`@ammaratef45` from [RTM](https://resisttechmonopolies.online/) is honored to
+vouch.

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)
 

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.

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

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`
 
@@ -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=<server-domain> docker system prune --all --force` if you have multiple docker contexts).

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>