Merge branch 'main' of ssh://git.coopcloud.tech:2222/coop-cloud/docs.coopcloud.tech

Signed-off-by: p4u1 <p4u1@noreply.git.coopcloud.tech>

.drone.yml

@@ -5,18 +5,20 @@ steps:
   - name: build static
     image: plugins/docker
     settings:
-      username: thecoopcloud
+      username: 3wordchant
       password:
-        from_secret: thecoopcloud_password
-      repo: thecoopcloud/docs.coopcloud.tech
+        from_secret: git_coopcloud_tech_token_3wc
+      repo: git.coopcloud.tech/coop-cloud/docs.coopcloud.tech
       tags: latest
+      registry: git.coopcloud.tech
 
   - name: deployment
-    image: decentral1se/stack-ssh-deploy:latest
+    image: git.coopcloud.tech/coop-cloud/stack-ssh-deploy:latest
     settings:
       stack: coop_cloud_mkdocs
+      host: swarm-0.coopcloud.tech
       deploy_key:
-        from_secret: drone_ssh_swarm.autonomic.zone
+        from_secret: drone_ssh_swarm-0_coopcloud_tech
     depends_on:
       - build static
 

docs/abra/hack.md

@@ -19,7 +19,7 @@ post](http://hintjens.com/blog:106)).
 
 Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/coop-cloud/abra).
 
-Install [direnv](https://direnv.net), run `cp .envrc.sample .envrc`, then run `direnv allow` in this directory. This will set coopcloud repos as private due to [this bug.](https://git.coopcloud.tech/coop-cloud/coopcloud.tech/issues/20#issuecomment-8201). Or you can run `go env -w GOPRIVATE=coopcloud.tech` but I'm not sure how persistent this is.
+Install [direnv](https://direnv.net), run `cp .envrc.sample .envrc`, then run `direnv allow` in this directory. Or you can run `go env -w GOPRIVATE=coopcloud.tech` but I'm not sure how persistent this is.
 
 Install [Go >= 1.16](https://golang.org/doc/install) and then:
 

docs/federation/membership.md

@@ -12,9 +12,10 @@ title: Membership
 | [Doop.coop](https://doop.coop) | - | - | `@yusf:gottsnack.net` |
 | [EOTL](https://eotl.supply) | - | - | `@basebuilder:pub.solar` |
 | [Karrot](https://karrot.world) | - | - | `@nicksellen:matrix.org` |
-| [Klasse & Methode](https://codeberg.org/Klasse-Methode) | - | - | `@p4u1_f4u1:matrix.org` |
-| [Local IT](https://local-it.org/)  | - | - | Philipp (`@yksflip:matrix.kaputt.cloud`) + `@moritz:matrix.local-it.org` |
+| [Klasse & Methode](https://klasse-methode.it) | - | - | `@p4u1_f4u1:matrix.org` |
+| [Local IT](https://local-it.org/)  | - | - | `@moritz:matrix.local-it.org` + `@simon_sth:matrix.org`|
 | Mirsal ™  | - | - | `@mirsal:1312.media` |
 | [UTAW](https://utaw.tech) | -  | - | `@javielico:matrix.org` |
 | [BeWater](https://bewater.contact) | Waiver | - | `@decentral1se` |
 | [ruangrupa](https://ruangrupa.id) | - | - | Henry `@babystepper:matrix.org` |
+| [Ammar](https://social.coop/@ammaratef45) | - | - | `@ammaratef45:matrix.org` |

docs/federation/minutes/2024-08-15.md

@@ -0,0 +1,54 @@
+# Coopcloud Meeting August
+
+## Agenda
+
+* Federation Stuff / Current state
+* Funding for Maintenance work
+* Design Operator Collaboration https://git.coopcloud.tech/coop-cloud/organising/issues/467
+* HOWTO finish Restore https://git.coopcloud.tech/coop-cloud/backup-bot-two/issues/42
+
+### Introductions
+
+- Moritz (Local IT): merging with Make IT Social (another collective), Maintanining Recipes, Maintainig Backupbot, Small fixes in the abra tool
+
+- p4u1 (Klasse & Methode): maybe starting a workers collective, maintaning some recipes and created a new one (for internal use for now), introduces abra config and a step towards operator collaboration
+
+- basebuilder (eotl): deep in eotl, trying to get stable releases out, abra recipes for both exists, in november / december some spare cycles for coopcloud, nlnet grant was rejected
+
+### Funding Maintenance Work
+
+a good idea by d1, would be nice if we can get one or two persons to commit to this. local it might have some resource at the end of the year. could also fund people for just one or two months (instead of per feature)
+
+5000€ in bank account. 10 hrs for orga and 20 hrs for hacking = 600€. would result into about 8 months paid work
+
+- write a propsal @p4u1
+- ask people if they can commit @everyone asks in their collective
+
+### Backupbot
+
+- spec: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/pulls/258
+
+- what to do if multiple backupbot.backup=false / true
+  - backupbot will ignore false if true was set
+  - add recipe lint
+
+- How to enable / disable per app
+  - backupbot.backup=${BACKUPBOT_ENABLE:-true}
+
+- Backup can't be used without backupbot
+  - it's ok for now, can also implement it later
+
+- Whats left
+  - restore and some backup labels
+
+- restore is tryicky to implement automatically
+  - for database e.g. other connections to it should be stopped
+
+- backwards compatible?
+  - introduce a new version label
+
+- moritz is going to implement the specification
+
+### Next Meeting
+
+- @moritz poll for lasst 2 weeks in september

docs/federation/organisers.md

@@ -0,0 +1,39 @@
+---
+title: Organisers
+---
+
+Welcome to the organisers guide! Organisers are folks who focus on the social work in the project. Speaking for the project at talks, helping new tech co-ops & collectives join, keeping an eye out for funding opportunities, seeing what things come up in the community chats, etc. It's important work.
+
+<div class="grid cards" markdown>
+
+- __Organisers Handbook__
+
+    One-stop shop for all you need to know to organise in the community :sparkles:
+
+    [Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
+
+- __Say Hello First__
+
+    If you like what you see, but are not sure how to best contribute :speech_left:
+
+    [Get In Touch](/get-involved/){ .md-button .md-button--primary }
+
+</div>
+
+We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:
+
+## Kite Flying Hours
+
+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.
+
+Here is some invitation boilerplate which you can use:
+
+> Hey folks, you're all warmly invited to the Co-op Cloud Kite Flying Hour at `$X_TIME` `$Y_TZ` `$Z_DATE` over in [vs.autistici.org/CoopCloudKiteFlyingHour](https://vs.autistici.org/CoopCloudKiteFlyingHour)!
+>
+> Inspired by exquisite childhood memories of [flying kites, eating popsicles and looking at clouds](https://norwichhistory.org/norwich-a-z-j-is-for-jigsaw/), it's an open hour to come hang out online and discuss/co-work/lurk/etc. around the [Co-op Cloud](https://coopcloud.tech/) project.
+>
+> There are no "stupid questions"! It's a space to inquire, be curious and have a good time and get to know each other.
+>
+> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/VtyrLUl9RWaJGgEDrncQUw). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.

docs/federation/proposals/federation.md

@@ -61,7 +61,7 @@ As a member of Co-op Cloud, you'll be able to:
 
 - Receive announcements about opportunities for funded work on Co-op Cloud early, before they're sent out to the wider community.
 
-- Use shared Co-op Cloud services, including code hosting ([git.coopcloud.tech](https://git.coopcloud.tech)), continuous deployment ([builds.coopcloud.tech](https://builds.coopcloud.tech)) and any future digital infrastructure we all decide to set up.
+- Use shared Co-op Cloud services, including code hosting ([git.coopcloud.tech](https://git.coopcloud.tech)), continuous deployment ([build.coopcloud.tech](https://build.coopcloud.tech)) and any future digital infrastructure we all decide to set up.
 
 ### Responsibilities
 

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

@@ -0,0 +1,68 @@
+# Resolution 025 Maintainers Proposal
+
+- Topic:  Maintainers Proposal
+- Date: 05-12-2024
+- Deadline:
+- Size: Large
+
+## Summary
+
+Create policies on recipe maintainence that meet industry standards, for example the designation of a recipe as stable or not if the recipe meets a certain critera and having named maintainers.
+
+## Details
+
+Currently the CC recipes ecosystem is quite unclear. Some recipes are maintained really well and some are abandoned. 
+
+I propose that we adopt a "stable", "testing", "unstable" designation to help organise our recipes internally and present them in a clearer way externally.
+
+We should take influence from the largest democratic software project [Debian](https://www.debian.org/doc/manuals/developers-reference/pkgs.en.html#) and implement a simplifier system of recipe maintainers to help build trust with our community and potential community members.
+
+### Who are maintainers
+
+Maintainers can be either fedi members, community collaborators or organisation collaborators (such as tech co-ops).
+
+Maintainers will need to provide some way of contacting them e.g. and email address or Matrix handle.
+
+Maintainers are welcome to use a handle/alias.
+
+### Stable
+
+"Stable" recipes must meet the following critera:
+
+- Must have at least one named maintainer (handle is fine) with a matrix or email address and that infomation must be kept up to date in the README
+- The upstream project must be considered active and able to respond to security issues
+- Security issues in the recipe must be patched within one month of discovery
+- Merge requests must be responded to with some form of aknowlegement or feedback within one month
+- Has been upgraded in the last three months (if appropriate)
+- The status score and README of the project should be kept up to date with relevant infomation
+
+### Testing
+
+"Testing" recipes must meet the following critera:
+
+- Must have at least one named maintainer (handle is fine) with a matrix or email address and that infomation must be kept up to date in the README
+- The upstream project must be considered active and able to respond to security issues
+- Security issues in the recipe must be patched within one month of discovery
+
+### Unstable
+
+"Unstable" recipes must meet the following critera:
+- Must have at least one named maintainer (handle is fine) with a matrix or email address and that infomation must be kept up to date in the README
+
+### Unmaintained
+
+If no one claims active responsibility for a recipe, its git repo will be archived and removed from the recipe catalouge.
+
+## Implementation
+
+- Docs updates to include explanations
+- Ongoing coworks to add catergories to all recipes
+- Package maintenance status will be added to the README's metdata on all recipes. Rname existing "Status" to Features, use Status for this maintenance status.
+- Add maintenance status to be visible on recipes.coopcloud.tech
+- Every three months we go through the recipes and garden the status is and ping maintainer's etc.
+
+# Pre-Propose Feedback from community
+* ~~Are maintainers community members or fedi members?~~
+* ~~Should we add a requirement that stable recipe has to respond to issues and/or PRs within x amount of time?~~
+* ~~will there be some form of automated check whether or not a recipe still fulfills a category's criteria?~~
+* ~~What happens to recipes not fulfilling any criteria? e.g. having no maintainer. need for another category?~~

docs/federation/resolutions/index.md

@@ -14,11 +14,11 @@ title: Resolution <number>
 - Deadline: Date
 - Size: large or medium
 
-### Summary
+## Summary
 
 Who this affects, and what it does...
 
-### Details
+## Details
 
 A narrative with details...
 ```

docs/federation/resolutions/passed/021.md

@@ -0,0 +1,57 @@
+---
+title: "Resolution 021"
+---
+
+- Topic: Budget 011: Migrate to Cobra
+- Date: 22-07-2024
+- Deadline: 31-07-2024
+- Size: Large
+
+### Summary
+
+Migrate away from our current command-line dependency so `abra` usage is more predictable. The goal is to maintain feature parity with no breaking changes. The main advantage that we will get is robust and flexible handling of flags/arguments which don't depend on forcing a specific order (see [`#581`](https://git.coopcloud.tech/coop-cloud/organising/issues/581)). There are other bonuses such as built-in support for auto-completion, better handling of example usage, improved support for global flags (`--debug`) and manpage support.
+
+### Details (Budget 011)
+
+#### The problem
+
+The current help output of `abra app deploy` is as follows:
+
+`abra app deploy [command options] <domain> [<version>]`
+
+However, it is possible to do both of the following:
+
+```
+abra app deploy --chaos example.org  # "before" style
+abra app deploy example.org --chaos  # "after" style
+```
+
+However, `abra app cmd` is broken if you try to use the "after" style:
+
+```
+abra app cmd <domain> <function> --local -- <args>
+```
+
+This results in `<recipe> doesn't have a --local function` which is a bug in the `abra` code. It tries to read the position of the arguments but `--local` is included as an argument. The bug in `abra` is due to a bug in `urfave/cli` - "after" style options appear as arguments 😱
+
+The only way to use `abra app cmd` right now is using the "before" style:
+
+```
+abra app cmd  --local <domain> <function> -- <args>
+```
+
+This means that some commands allow both "after" and "before" style and some only allow "before" style. This is a source of confusion, raised issues and frustration.
+
+#### The solution
+
+[Several](https://git.coopcloud.tech/coop-cloud/abra/pulls/404) [attempts](https://git.coopcloud.tech/coop-cloud/abra/pulls/435) have been made to upgrade `urfave/cli` to fix this behaviour. However, as it turns out, it is **highly unlikely** that they will fix this upstream: [`urfave/cli#1950`](https://github.com/urfave/cli/issues/1950) [`urfave/cli#1928`](https://github.com/urfave/cli/pull/1928) (and even this proposal does not really include the desired robust flexible handling we need).
+
+`@decentral1se` has done a spike to confirm that [`cobra`](https://cobra.dev) handles flexible handling of arguments/flags. Those reading this proposal and wishing to try it out for themselves can take [Hugo](https://gohugo.io/) for a spin (it uses `cobra` as the underlying command-line library).
+
+This tool is well maintained and used by several large projects such as Hugo and Kubernetes. The library matches all functionality we require.
+
+#### Budget
+
+`@decentral1se` can carry out this work.
+
+Proposed budget of 15 hrs: `15 hrs * 20 = 300 EUR`

docs/federation/resolutions/passed/022.md

@@ -0,0 +1,28 @@
+---
+title: "Resolution 022"
+---
+
+- Topic: Ammar joins the Co-op Cloud Federation
+- Date: 31-08-24
+- Deadline: 14-09-2024
+- Size: Large
+
+### Summary
+
+> @ammaratef45:matrix.org
+
+[@ammaratef45](https://git.coopcloud.tech/ammaratef45) is a software engineer and has:
+
+- Used Co-op Cloud for self-hosting libre apps.
+- Advocated for self hosting in his community in Seattle.
+- Participated in [https://matrix.to/#/#coopcloud-tech:autonomic.zone](our community) chats.
+- Some small contributions/fixes/bug reports for some Co-op Cloud stuff.
+- Published an abra recipe for photo prism.
+
+### Details
+
+I, Ammar Hussein, believe in the vision of Co-op Cloud and been invested in the
+success of similar initiatives. I would love the opportunity to fomrmally
+become a member of the federation and happy to contribute membership dues.
+
+[Be Water](https://bewater.contact) is happy to vouch.

docs/federation/resolutions/passed/023.md

@@ -0,0 +1,50 @@
+---
+title: Resolution 023
+---
+
+- Topic: Budget 012: Feedback gathering and content architecture for the new Co-op Cloud website
+- Date: 04-09-2024
+- Deadline: 18-09-2024
+- Size: Large
+
+### Summary
+
+There is general interest in a new public-facing website for Co-op Cloud which can:
+
+- Motivate new helping hands to join in
+- Attract diverse funding for the project (which is not based purely on technical implementation)
+
+It hasn't been reworked in quite some time (guestimate: 2 years). 
+
+This proposal describes a way to do this and includes a budget for doing so.
+
+### Details (Budget 012)
+
+The current state of the splash page consists of the following contents:
+    
+- **Introduction** (Broad explanation)
+- **Benefit** (Why use it)
+- **Frequently Asked Questions**
+- **Groups which use it**
+- **Involved groups and funders**
+
+The goal would be to collect feedback from the community and compile it into different requirements and tasks.
+
+We believe the first 2 tasks to get started are as follows:
+
+- **Collect feedback**: Create forms or markdown based questionares and motivate members, users, enthusiasts to answer these.
+
+- **Content architecture**: Design what is written where and why so that visitors can quickly grasp the big picture and get excited about it.
+
+Once feedback and architecture work is wrapped up, we're in a good place to work on the remaining tasks: copywriting, design and finally, the frontend development work. More proposals will follow.
+
+## Budget
+    
+Budget details:
+
+| Item | Cost | Who? |
+| ---- | ---- | ---- |
+| Feedback | 8 hours | `@kimble` |
+| CA/UX | 10 hours | `@kimble` |
+
+**Total: 18 hrs * 20 EUR = 360 EUR**

docs/federation/resolutions/passed/024.md

@@ -0,0 +1,52 @@
+# Resolution 024: Budget: 013: Reintroduce kite-flying
+
+- Topic: Reintroduce paid kite-flying hour
+- Date: 2024-10-30
+- Deadline: 2024-11-13
+- Size: Large
+
+## Summary
+
+Allocate up to €2000 to paying attendees for their presence at weekly "kite-flying hours".
+
+## Details
+
+During the phase of ECF-funded work, Co-op Cloud had "kite-flying hours", an informal weekly call. We stopped doing these at the end of the ECF funding. Currently, our only chance for synchronous check-in with other folks in the Co-op Cloud Community is monthly federation meetings which, as well as only being open to members of the federation, are also proving difficult to organise.
+
+This resolution proposes reintroducing kite-flying hours, initially with a rotating slot that alternates between 12 UTC and 19 UTC on Thursdays in order to accommodate folks in different timezones.
+
+This schedule can be changed as necessary via a Medium decision.
+
+Attendance of kite-flying hours is paid at the standard €20/h rate.
+
+This budget is expected to last around 4.5 months, assuming up to 5 weekly paid attendees at kite-flying sessions.
+
+Time during kite-flying sessions can be spent on anything useful to the Co-op Cloud Federation; some examples could be:
+
+- Co-working, e.g.:
+  - abra development
+  - recipe maintenance
+  - documentation
+  - funding applications
+  - writing resolutions
+  - developing posts for social media, or the website blog
+  - federation admin (membership, finance)
+  - infrastructure maintenance
+- Welcoming new members of the co-op cloud community
+- Supporting community members with technical issues
+- Holding informal discussions / polls about any aspect of co-op cloud
+
+### Budget 013: Kite-flying 2024-2025
+
+> **Budget amount:** EUR 2000
+>
+> **Who will implement this:** 3wordchant
+>
+> **When will the money be spent:** Until the budget is exhausted; expected to be around the end of March 2025
+>
+> **What is the money for:** Paying attendees of weekly "kite-flying" sessions
+
+## Questions
+
+3wc: Should this be open to anyone in the community, or just federation members? If it's completely open, are there are any expectations / criteria, or could someone literally get paid to come listen in every week?
+KP: I think we just monitor that and if there's any problematic behaviour, we may need to change course.

docs/hosters/handbook.md

@@ -41,7 +41,7 @@ For a simple example check the [entrypoint.sh for `croc`](https://git.coopcloud.
 
 If you write your own entrypoint, it needs to be specified in the `config` section of compose.yml. See [this handbook entry](/maintainers/handbook/#how-do-i-set-a-custom-entrypoint) for more.
 
-### `releases/` directory
+### `release/` directory
 
 This directory contains text files whose names correspond to the recipe versions which have been released and contain useful tips for operators who are doing upgrade work. See [this handbook entry](/maintainers/handbook/#how-do-i-write-version-release-notes) for more.
 
@@ -396,11 +396,11 @@ mkdir -p release
 
 And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
 
-You can also add release notes for the next release into a special file `releases/next`. This file will be used when running `abra recipe release`.
+You can also add release notes for the next release into a special file `release/next`. This file will be used when running `abra recipe release`.
 
 !!! warning "Not available previous versions of Abra"
 
-    Using `releases/next` is only available in > 0.9.x series of `abra`.
+    Using `release/next` is only available in > 0.9.x series of `abra`.
 
 ## How do I generate the recipe catalogue
 

docs/hosters/tutorial.md

@@ -52,6 +52,17 @@ Open the `compose.yml` in your favourite editor and have a gander 🦢. The
 
 The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
 
+### Updating the `.env.sample`
+
+Open the `.env.sample` file and add the following
+
+```
+DB_PASSWORD_VERSION=v1
+DB_ROOT_PASSWORD_VERSION=v1
+```
+
+The resulting `.env.sample` is available [here](https://git.coopcloud.tech/coop-cloud/matomo/src/branch/main/.env.sample)
+
 ### Test deployment
 
 !!! note "Running Co-op Cloud server required!"

docs/intro/faq.md

@@ -175,3 +175,18 @@ By using Co-op Cloud infrastructure over private cloud infrastructure, you creat
 - You may interact with a server provider that is more ethical than Big Tech. Although the server provider may still succumb to law enforcement, you might place more trust in some providers than in private cloud providers (e.g. AWS).
 
 - You may be able to situate your servers in locations that are relatively more impervious to law enforcement attempts to dismantle your infrastructure. Indeed, if you deployed your infrastructure in a relatively secure setting such as Switzerland, then you would weather a greater chance of keeping your infrastructure alive than if you deployed it in, say, the United States. Protonmail and [Extinction Rebellion (XR)](https://www.youtube.com/watch?v=I_O3zj3p52A) choose Switzerland for their servers, for reasons along these lines.
+
+## Why are named volumes used instead of bind mounts?
+
+Many folks using Docker are probably used to using bind mounts; these are recommended in many (most?) upstream docker-compose files, and at one point Docker recommended bind mounts over named mounts due to poor performance of the Linux named volume storage drivers.
+
+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)
+
+Following these recommendations, Co-op Cloud exclusively uses named volumes (except for rare special-case bind mounts, like Traefik and Caddy getting access to the host's `/var/run/docker.sock`).

docs/intro/managed.md

@@ -8,6 +8,6 @@ title: Managed hosting
 
 The Co-op Cloud is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: but you can still work with a tech co-op or collective to host some part or all of your online digital services with it. Organisations who want to support the project can get in touch with Co-op Cloud service providers via the following list for a quote on what they're looking for and how much it will cost. Service providers can then factor in some percentage of the cost to co-fund the development of this project.
 
-- [Autonomic Co-op](https://autonomic.zone) (contact: [`helo@autonomic.zone`](mailto:helo@autonomic.zone))
+- [Autonomic Co-op](https://autonomic.zone) (contact: [`helo@autonomic.zone`](mailto:boop@autonomic.zone))
 - [Local-IT](https://local-it.org/) (contact [`info@local-it.org`](mailto:info@local-it.org))
 - [Solisoft](https://solisoft.top) (contact [`contact@solisoft.top`](mailto:contact@solisoft.top))

docs/organisers/index.md

@@ -1,23 +0,0 @@
----
-title: Organisers
----
-
-Welcome to the organisers guide! Organisers are folks who focus on the social work in the project. Speaking for the project at talks, helping new tech co-ops & collectives join, keeping an eye out for funding opportunities, seeing what things come up in the community chats, etc. It's important work.
-
-<div class="grid cards" markdown>
-
-- __Organisers Handbook__
-
-    One-stop shop for all you need to know to organise in the community :sparkles:
-
-    [Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
-
-- __Say Hello First__
-
-    If you like what you see, but are not sure how to best contribute :speech_left:
-
-    [Get In Touch](/get-involved/){ .md-button .md-button--primary }
-
-</div>
-
-We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:

docs/specs/backup/index.md

@@ -0,0 +1,3 @@
+---
+title: Backup
+---

docs/specs/backup/maintain.md

@@ -0,0 +1,166 @@
+# For Maintainers
+
+From the perspective of the recipe maintainer, backup/restore is just more
+`deploy: ...` labels. Tools can read these labels and then perform the
+backup/restore logic.
+
+## Tools
+
+Two of the current "blessed" options are, which both implement the [backupbot specification](link to spec)
+
+- [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)
+- [`abra`](https://git.coopcloud.tech/coop-cloud/abra)
+
+### `backup-bot-two`
+
+`backup-bot-two` is a recipe which gets deployed on the server, it can perform automatic backups and uses restic.
+Please see the [`README.md`](https://git.coopcloud.tech/coop-cloud/backup-bot-two#backupbot-ii) for the full docs.
+
+### `abra`
+
+`abra` will read labels and store backups in `~/.abra/backups/...` .
+It also provides an integration for `backup-bot-two`.
+
+## Backup
+
+### How to Configure backups
+
+Unless otherwise stated all labels should be added to the main service (which should be named `app`).
+
+1. Enable backups for the recipe:
+   You need to enable backups for the recipe by adding the following deploy label:
+
+```
+backupbot.backup=true
+```
+
+2. Decide wich volumes should be backed up:
+   By default all volumes will be backed up. To disable a certain volume you can add the following deploy label:
+
+```
+backupbot.backup.volumes.{volume_name}=false
+```
+
+3. Decide which path should be backed up on each volume
+   By default all files get backed up for a volume. To only include certain paths you can add the following deploy label:
+
+```
+backupbot.backup.volumes.{volume_name}.path=/mypath1/foo,/mypath2/bar
+```
+
+Note: You can include multiple paths by providing a comma seperated list
+Note: All paths are specified relativ to the volume root
+
+4. Run commands before the backup
+   For certain services like a database it is not reccomend to just backup files, because the backup might end up in a corrupted state. Instead it is reccomended to make a database dump. You can run arbitrary commands in any container before the files are backed up.
+   To do this add the following deploy label to the service on which you want the command being run:
+
+```
+backupbot.backup.pre-hook=mysqldump -u root -pghost ghost --tab /var/lib/foo
+```
+
+5. Run commands after the backup
+   Sometimes you want to clean up after the backup. You can run arbitrary commands in any container after the files were backed up.
+   To do this add the following deploy label to the service on which you want the command being run:
+
+```
+backupbot.backup.post-hook=rm -rf /var/lib/mysql-files/*
+```
+
+### Testing the backup
+
+To test that your backup is configured correctly you can deploy the recipe you are working on in a test app either [locally](link to local server deployment) or on a test server.
+
+After the deployment is succesfull run the backup and inspect its content
+
+```
+abra app backup myrecipe.example.com
+tar -tf ~/.abra/backups/mybackup
+```
+
+TODO: this is not complete yet
+
+## Restore
+
+When restoring an app, it takes the files from a backup and copies them to their correct location.
+In the case of restoring database tables, you can use the `pre-hook` & `post-hook` commands to run the insertion logic.
+
+## Pre and Post hooks
+
+To back up some services correctly it involves more than just copying a few files from one location to another. Some services already have specific backup tools that allow taking a coherent snapshot of its data like `mysqldump`.
+The pre and post hooks can be used to prepare the files which should get backed up and clean up afterwards.
+
+Here are some examples:
+
+### Example 1: Execute simple command
+
+```
+backupbot.backup.pre-hook: "echo 'foo' > /path/to/volume/bar.txt
+```
+
+### Example 2: Access environment variable
+
+```
+backupbot.backup.pre-hook: "cat $${POSTGRES_PASSWORD_FILE}"
+```
+
+### Example 3: Access secret
+
+```
+backupbot.backup.pre-hook: "cat /var/run/secrets/mysupersecret"
+```
+
+```
+backupbot.backup.pre-hook: 'mysqldump -p"$$(cat /run/secrets/mysupersecret)" mydatabase'
+```
+
+### Example 4: Complex script
+
+Sometimes the logic to backup up a service can get quite complex. In that case it might be easier to add a script (via mount or config) inside the container and call that from the pre and post hook:
+
+```
+backupbot.backup.pre-hook: "/scripts/my-pre-backup-scripts"
+backupbot.backup.post-hook: "/scripts/my-post-backup-scripts"
+```
+
+## Configuration Examples
+
+### Mariadb
+
+```
+services:
+  db:
+    image: mariadb
+    volumes:
+      - "mariadb:/var/lib/mysql"
+    deploy:
+      labels:
+        backupbot.backup: "true"
+        backupbot.backup.pre-hook: "sh -c 'mariadb-dump --single-transaction -u root -p\"$$(cat /run/secrets/db_root_password)\" wordpress | gzip > /var/lib/mysql/dump.sql.gz'"
+        backupbot.backup.volume.mariadb.path: "dump.sql.gz"
+        backupbot.backup.post-hook: "rm -f /var/lib/mysql/dump.sql.gz"
+        backupbot.restore.post-hook: "sh -c 'gzip -d /var/lib/mysql/dump.sql.gz && mariadb -u root -p\"$$(cat /run/secrets/db_root_password)\" wordpress < /var/lib/mysql/dump.sql && rm -f /var/lib/mysql/dump.sql'"
+```
+
+### Postgres
+
+```
+version: '3.8'
+
+services:
+  db:
+    image: "postgres"
+    volumes:
+      - "postgres:/var/lib/postgresql/data"
+    secrets:
+      - db_password
+    deploy:
+      labels:
+            backupbot.backup: "true"
+            backupbot.backup.pre-hook: "PGPASSWORD=$$(cat $${POSTGRES_PASSWORD_FILE}) pg_dump -U $${POSTGRES_USER} $${POSTGRES_DB} > /var/lib/postgresql/data/backup.sql"
+            backupbot.backup.post-hook: "rm -rf /var/lib/postgresql/data/backup.sql"
+            backupbot.backup.volume.postgres.path: "backup.sql"
+
+volumes:
+  postgres:
+```

docs/specs/backup/spec.md

@@ -0,0 +1,136 @@
+# Specification
+
+## Summary
+
+Creating automated backups of docker swarm services is an often needed task. This specification describes how backups can be configured via [service labels](https://docs.docker.com/compose/compose-file/compose-file-v3/#labels-1) in a standardised way.
+
+## Requirements
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+## Backup
+
+To enable backups for a docker stack, the `backupbot.backup=true` label MUST be set on one of its services. The label MUST NOT be set multiple times for a docker stack. Otherwise the implementation MUST show an error. The label SHOULD be declared on the main service.
+
+### Volumes and paths
+
+By default all volumes MUST be backed up. A volume MUST be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume.
+By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get separated by a comma. When the label is set only the given paths MUST be backed up.
+
+### Pre/Post Hooks
+
+A `backupbot.backup.pre-hook` and `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after backing up files.
+There is no guaranteed order in which different hooks MUST be executed.
+
+TODO: escaping
+
+### Output
+
+A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{stack_name}_{volume_name}`, where `{stack_name}` is the name of the docker stack and `{volume_name}` is the name of each volume that got backed up.
+
+## Restore
+
+By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. When restoring a backup from a `.tar.gz` it expects the directory layout as described in the [backup output](#output) section.
+
+### Pre/Post Hooks
+
+A `backupbot.restore.pre-hook` and `backupbot.restore.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after restoring the files.
+There is no guaranteed order in which different hooks MUST be executed.
+
+## Labels
+
+### `backupbot.backup`
+
+**Type:** boolean
+**Default:** false
+**Description:**
+Enables backups for this compose stack. The label should be added to the main service of the compose stack.
+
+**Example:**
+
+```
+backupbot.backup: true
+```
+
+### `backupbot.backup.volumes.{volume_name}`
+
+**Type:** boolean
+**Default:** true
+**Description:** When set to false the volume is excluded from backups.
+
+**Example:**
+
+```
+backupbot.backup.volumes.{volume_name}: false
+```
+
+### `backupbot.backup.volumes.{volume_name}.path`
+
+**Type:** string
+**Default:** ""
+**Description:**
+A comma seperated list of paths. When one or more paths are set, it only backs up those on the given volume instead of the whole volume.
+
+**Example 1:**
+
+```
+backupbot.backup.volumes.{volume_name}.path: '/var/lib/mariadb/dump.sql.gz'
+```
+
+**Example 2:**
+```
+backupbot.backup.volumes.{volume_name}.path: '/var/lib/myapp/foo,/var/lib/myapp/bar'
+```
+
+### `backupbot.backup.pre-hook`
+
+**Type:** string
+**Default:** ""
+**Description:**
+A command, that gets executed before the files are backed up.
+
+**Example:**
+
+```
+backupbot.backup.pre-hook: 'mysqldump -u root -p"$(cat /run/secrets/db_root_password)" -f /volume_path/dump.db'
+```
+
+### `backupbot.backup.post-hook`
+
+**Type:** string
+**Default:** ""
+**Description:**
+A command, that gets executed after the files are backed up.
+
+**Example:**
+
+```
+backupbot.backup.post-hook: "rm -rf /volume_path/dump.db"
+```
+
+### `backupbot.restore.pre-hook`
+
+**Type:** string
+**Default:** ""
+**Description:**
+A command, that gets executed before the files are restored.
+Note, that there is no guaranteed order in which multiple hooks get executed.
+
+**Example:**
+
+```
+backupbot.restore.pre-hook: "lock db"
+```
+
+### `backupbot.restore.post-hook`
+
+**Type:** string
+**Default:** ""
+**Description:**
+A command, that gets executed after the files are restored.
+
+**Example:**
+
+```
+backupbot.restore.post-hook: "sqldump dump.sql && unlock db && rm dump.sql"
+```

docs/specs/index.md

@@ -0,0 +1,3 @@
+---
+title: Specifications
+---

mkdocs.yml

@@ -1,6 +1,6 @@
 ---
 site_author: Co-op Cloud
-site_name: "Co-op Cloud: Docs" 
+site_name: "Co-op Cloud: Docs"
 site_url: https://docs.coopcloud.tech
 use_directory_urls: true
 
@@ -78,15 +78,15 @@ nav:
       - organisers/index.md
       - "Organisers Handbook": organisers/handbook.md
       - "Funding applications":
-        - organisers/funding-applications/index.md
-        - organisers/funding-applications/culture-of-solidarity.md
-        - organisers/funding-applications/ford-foundation.md
-        - organisers/funding-applications/private-funder.md
-        - organisers/funding-applications/sovereign-tech-fund.md
-        - organisers/funding-applications/user-operated-internet.md
+          - organisers/funding-applications/index.md
+          - organisers/funding-applications/culture-of-solidarity.md
+          - organisers/funding-applications/ford-foundation.md
+          - organisers/funding-applications/private-funder.md
+          - organisers/funding-applications/sovereign-tech-fund.md
+          - organisers/funding-applications/user-operated-internet.md
       - "Proposals":
-        - organisers/proposals/index.md
-        - organisers/proposals/federation.md
+          - organisers/proposals/index.md
+          - organisers/proposals/federation.md
   - "Abra":
       - abra/index.md
       - "Install": abra/install.md
@@ -107,41 +107,49 @@ nav:
       - "Membership": federation/membership.md
       - "Code of Co-operation": federation/code-of-coop.md
       - "Resolutions":
-        - federation/resolutions/index.md
-        - "Passed":
-          - federation/resolutions/passed/001.md
-          - federation/resolutions/passed/002.md
-          - federation/resolutions/passed/003.md
-          - federation/resolutions/passed/004.md
-          - federation/resolutions/passed/005.md
-          - federation/resolutions/passed/006.md
-          - federation/resolutions/passed/007.md
-          - federation/resolutions/passed/008.md
-          - federation/resolutions/passed/009.md
-          - federation/resolutions/passed/010.md
-          - federation/resolutions/passed/011.md
-          - federation/resolutions/passed/012.md
-          - federation/resolutions/passed/014.md
-          - federation/resolutions/passed/015.md
-          - federation/resolutions/passed/016.md
-          - federation/resolutions/passed/017.md
-          - federation/resolutions/passed/018.md
-          - federation/resolutions/passed/019.md
-          - federation/resolutions/passed/020.md
-        - "In Progress":
-          - federation/resolutions/in-progress/013.md
+          - federation/resolutions/index.md
+          - "Passed":
+              - federation/resolutions/passed/001.md
+              - federation/resolutions/passed/002.md
+              - federation/resolutions/passed/003.md
+              - federation/resolutions/passed/004.md
+              - federation/resolutions/passed/005.md
+              - federation/resolutions/passed/006.md
+              - federation/resolutions/passed/007.md
+              - federation/resolutions/passed/008.md
+              - federation/resolutions/passed/009.md
+              - federation/resolutions/passed/010.md
+              - federation/resolutions/passed/011.md
+              - federation/resolutions/passed/012.md
+              - federation/resolutions/passed/014.md
+              - federation/resolutions/passed/015.md
+              - federation/resolutions/passed/016.md
+              - federation/resolutions/passed/017.md
+              - federation/resolutions/passed/018.md
+              - federation/resolutions/passed/019.md
+              - federation/resolutions/passed/020.md
+              - federation/resolutions/passed/021.md
+              - federation/resolutions/passed/022.md
+              - federation/resolutions/passed/023.md
+              - federation/resolutions/passed/024.md
+          - "In Progress":
+              - federation/resolutions/in-progress/025.md
       - "Minutes":
-        - federation/minutes/index.md
-        - "Recently":
-          - federation/minutes/2024-04-17.md
-          - federation/minutes/2024-03-29.md
-        - "Archive":
-          - federation/minutes/2024-02-01.md
-          - federation/minutes/2022-03-03.md
-          - federation/minutes/2023-05-03.md
+          - federation/minutes/index.md
+          - "Recently":
+              - federation/minutes/2024-04-17.md
+              - federation/minutes/2024-03-29.md
+          - "Archive":
+              - federation/minutes/2024-02-01.md
+              - federation/minutes/2022-03-03.md
+              - federation/minutes/2023-05-03.md
       - "Digital Tools": federation/tools.md
+  - "Specifications":
+      - "Backups":
+          - specs/backup/maintain.md
+          - specs/backup/spec.md
   - "Glossary":
-    - glossary/index.md
+      - glossary/index.md
 
 plugins:
   - awesome-pages