docs/maintainers/handbook.md aktualisiert

clarification of necessity of `command:` in case of custom entrypoint (and where to find it)

.drone.yml

@@ -5,35 +5,22 @@ steps:
   - name: build static
     image: plugins/docker
     settings:
-      username: thecoopcloud
+      username: abra-bot
       password:
-        from_secret: thecoopcloud_password
-      repo: thecoopcloud/docs.coopcloud.tech
+        from_secret: git_coopcloud_tech_token_abra_bot
+      repo: git.coopcloud.tech/toolshed/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
-
-  - name: notify coopcloud-dev on failure
-    image: plugins/matrix
-    settings:
-      homeserver: https://matrix.autonomic.zone
-      roomid: "IFazIpLtxiScqbHqoa:autonomic.zone"
-      userid: "@autono-bot:autonomic.zone"
-      accesstoken:
-        from_secret: autonobot_rocketchat_access_token
-    depends_on:
-      - build static
-      - deployment
-    when:
-      status:
-        - failure
 trigger:
   branch:
     - main

Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:9.5.7
+FROM squidfunk/mkdocs-material:9.5.49
 
 EXPOSE 8000
 

README.md

@@ -1,6 +1,6 @@
 # docs.coopcloud.tech :open_book:
 
-[![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/docs.coopcloud.tech/status.svg)](https://build.coopcloud.tech/coop-cloud/docs.coopcloud.tech)
+[![Build Status](https://build.coopcloud.tech/api/badges/toolshed/docs.coopcloud.tech/status.svg)](https://build.coopcloud.tech/toolshed/docs.coopcloud.tech)
 
 View: [docs.coopcloud.tech](https://docs.coopcloud.tech)
 

compose.yml

@@ -3,7 +3,7 @@ version: "3.8"
 
 services:
   app:
-    image: thecoopcloud/docs.coopcloud.tech:latest
+    image: git.coopcloud.tech/toolshed/docs.coopcloud.tech:latest
     networks:
       - proxy
     healthcheck:

docs/abra/cheat-sheet.md

@@ -7,62 +7,134 @@ title: Cheat sheet
 !!! info
     not all flags are listed here.
 
-!!! warning
-    Definitely set up autocomplete or you'll be sad
 
-    `abra autocomplete bash/zsh/fizsh`
+### Abra Autocomplete
 
-### create and deploy a new app:
-- `abra app new $RECIPE`
-flags: `-s/--server`, `-D/--domain`, `-S/--secrets`, `-p/--pass`
-- `abra app config $APPNAME`
-- `abra app secret generate $APPNAME -a`
-flags: `-p/--pass`, `-a/--all`
-- `abra app deploy $APPNAME`
-flags: `-f/--force`, `-C/--chaos`
+Definitely set up autocomplete or you'll be sad :sob: `abra` supports `bash`,
+`zsh`, and `fizsh` just run
 
-### undeploy and remove an app
-- back up any data you don't want to lose
-- `abra app undeploy $APPNAME`
-- `abra app rm --volumes $APPNAME`
-flags: `-f/--force`, `-V/--volumes`
+```
+$ abra autocomplete bash
+# Restart your terminal or load autocompletion in place
+$ source /etc/bash_completion.d/abra
+```
 
-### add/remove server
-- `abra server add $SERVER`
-- `abra server remove $SERVER`
-flags: `-s/--server`
 
-### upgrade abra
-- `abra upgrade`
-flags: `--rc`
+### Create & deploy an app
 
-### upgrade a recipe
-- `abra recipe upgrade $RECIPE`
-flags: `-x,y,z/--major,minor,patch`
-- `abra recipe sync $RECIPE`
-flags: `-x,y,z`
-- `abra recipe release $RECIPE [$VERSION]`
-flags: `-p/--publish`, `-r/--dry-run`, `-x,y,z`
+```
+$ abra app new $RECIPE`
+```
+
+Optional flags: `-s/--server`, `-D/--domain`, `-S/--secrets`, `-p/--pass`
+
+```
+$ abra app config $APPNAME
+$ abra app secret generate $APPNAME -a
+```
+
+Optional flags: `-p/--pass`, `-a/--all`
+
+```
+$ abra app deploy $APPNAME
+```
+
+Optional flags: `-f/--force`, `-C/--chaos`
+
+
+### Restarting an app
+
+To run `restart` you need to specify the `<service>` name with the default being `app`
+
+```
+$ abra app restart <domain> app
+```
+
+### Undeploy & remove an app
+
+Back up any data you don't want to lose
+
+```
+$ abra app undeploy $APPNAME
+$ abra app rm --volumes $APPNAME
+```
+
+Optional flags: `-f/--force`, `-V/--volumes`
+
+
+### Upgrade abra
+
+To upgrade `abra` itself, run the following:
+
+```
+$ abra upgrade
+```
+
+Option flags: `--rc`
+
+
+### Upgrade a recipe
+
+```
+$ abra recipe upgrade $RECIPE`
+```
+
+Option flags: `-x,y,z/--major,minor,patch`
+
+```
+$ abra recipe sync $RECIPE
+```
+
+Optional flags: `-x,y,z`
+
+```
+$ abra recipe release $RECIPE [$VERSION]
+```
+
+Optional flags: `-p/--publish`, `-r/--dry-run`, `-x,y,z`
+
+
+### Manually restoring app data
+
+To manually restore app data or configurations, you can use the `cp` command as:
+
+```
+$ abra app cp <domain> path/to/.app.conf app:/home/app/
+$ abra app cp <domain> path/to/data app:/home/app/
+```
+
+*Note: the destination must be a directory and not a filename*
+
+
+### Make changes to a recipe
+
+Edit the files in `~/.abra/recipe/$RECIPENAME`
+
+Deploy the changed version to your test instance
+
+Determine how serious your change is (semver.org for reference)
+
+```
+$ abra recipe release $RECIPE [$VERSION]
+```
 
-### make a change to a recipe
-- edit the files in `~/.abra/recipe/$RECIPENAME`
-- deploy the changed version to your test instance
-- determine how serious your change is (semver.org for reference)
-- `abra recipe release $RECIPE [$VERSION]`
 
 ### Advanced Listing using `jq`
 
 Several `abra` commands can output JSON formatted tables, and can thus be queried and filtered with the tool [jq](https://stedolan.github.io/jq/ "jq JSON Query tool"). We can also format these outputs with [tv](https://github.com/uzimaru0000/tv "tv Table Viewer") into a pretty table. 
 
-
 Currently, `abra recipe ls`, `abra server ls`, and `abra app ls` support the `-m` machine readable output flag which outputs JSON.
 
+
 #### Filter recipes by "category"
 
-`abra recipe ls -m | jq '[.[] | select(.category == "Utilities") ]' | tv`
+```
+$ abra recipe ls -m | jq '[.[] | select(.category == "Utilities") ]' | tv
+```
 
 As you can see we, we're selecting all recipes where category is "Utilities".
 
+
 #### Filter apps by state `deployed`
 
 !!! info 
@@ -71,9 +143,8 @@ As you can see we, we're selecting all recipes where category is "Utilities".
 !!! info 
     `abra app ls` lists apps grouped into a server object, with statistics about the server. In `jq` we can select the entire apps list with `.[].apps[]`.
 
-`abra app ls -m -S |jq '[.[].apps[] | select(.status == "deployed") | del(.upgrade)]' |tv`
+```
+$ abra app ls -m -S |jq '[.[].apps[] | select(.status == "deployed") | del(.upgrade)]' |tv
+```
 
 The `del(.upgrade)` filter filters out available versions for the recipe in question for that row. It could be useful to leave in if you want a list of deployed apps that need an upgrade.
-
-
-

docs/abra/design.md

@@ -0,0 +1,9 @@
+---
+title: Design
+---
+
+## Design Prime Directives
+
+* De-coupling: it should be possible to use the recipes without relying on
+  `abra`. The commons of recipes should live and function independently of
+  `abra`.

docs/abra/hack.md

@@ -2,11 +2,28 @@
 title: Hack
 ---
 
+## Contributing
+
+Welcome to Hacking the Planet with `abra`! We're looking forward to see what you come up. If you have any questions, don't hesitate to ask 💖 However, please keep in mind that if any of your changes seems a bit controversial, it's probably best to come have a chat first to avoid heartache.
+
+In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging" based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
+
+In other words, we're happy to give you, as contributor, "the commit bit" (read/write permissions on the Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
+
+We maintain a "team" called "Co-operators" on our 2 main repositories:
+
+* [`git.coopcloud.tech/org/toolshed`](https://git.coopcloud.tech/org/toolshed/)
+* [`git.coopcloud.tech/org/coop-cloud`](https://git.coopcloud.tech/org/coop-cloud/)
+
+This gives you read/write access to all the repositories of the organisation.
+
+Any existing contributor can add you.
+
 ## Quick start
 
-Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/coop-cloud/abra).
+Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/toolshed/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:
 
@@ -15,9 +32,9 @@ Install [Go >= 1.16](https://golang.org/doc/install) and then:
 - `make test` will run tests
 - `make install-abra` will install abra to `$GOPATH/bin`
 - `make install-kadabra` will install kadabra to `$GOPATH/bin`
-- `go get <package>` and `go mod tidy` to add a new dependency
+- `go get <package>`, `go mod tidy` and `go mod vendor` to add a new dependency
 
-Our [Drone CI configuration](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/Makefile) for more handy targets.
+Our [Drone CI configuration](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/toolshed/abra/src/branch/main/Makefile) for more handy targets.
 
 Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
 
@@ -41,19 +58,44 @@ go test ./pkg/recipe -v -run TestGetVersionLabelLocalDoesNotUseTimeoutLabel
 
 ## Integration tests
 
-### Install dependencies
+### Running on the CI server
 
-We use [`bats`](https://bats-core.readthedocs.io/en/stable/), you can install
-the required dependencies with the following. You also need a working
-installation of Docker and Go (not covered in this section).
+Based on [R020](https://docs.coopcloud.tech/federation/resolutions/passed/020/), we have automated running the integration test suite. Here's the TLDR;
+
+* We have a donated CI server (tysm `@mirsal` 💝) standing at the ready, `int.coopcloud.tech`.
+* We run the entire integration suite nightly via our Drone CI/CD configuration [here](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) (see "`name: integration test`" stanza)
+* Here is the script that is run on the remote server: [`run-ci-int`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/tests/run-ci-int)
+
+What follows is a listing of how this was achieved so that we can collectivise the maintenance.
+
+On the server, we have:
+
+* Created an `abra` user with `docker` permissions
+* Ran `apt install bats bats-file bats-assert bats-support jq make git golang-1.21 wget bash`
+* Installed `bats-core` from source, following the instructions below
+* Docker was already installed on the machine, so nothing to do there
+* `docker login` with the `thecoopcloud` details so we don't get rate limited
+
+The drone configuration was wired up as follows:
+
+* Generated a SSH key and put the public key part in `~/.ssh/authorize_keys`
+* Added that public key part as a "deploy key" in the abra repo (so we can do `ssh://` git remote pulls)
+* Added the private key part as a Drone secret which is available in build so that the build can SSH over to the server to run commands. That was done like so: `drone secret add --repository toolshed/abra --name abra_int_private_key --data @id_ed25519`
+* In order to specify a cron timing, you need to create it with the Drone CLI: `drone cron add "toolshed/abra" "integration" @daily --branch main`
+
+Please ask `@decentral1se` or on the Matrix channels for SSH access to the machine.
+
+### Running them locally
+
+#### Install dependencies
+
+We use [`bats`](https://bats-core.readthedocs.io/en/stable/) to run the tests. You can install the required dependencies with the following. You also need a working installation of Docker and Go >= 1.16 (not covered in this section).
 
 ```
 apt install bats-file bats-assert bats-support jq make git
 ```
 
-Unfortunately, the latest `bats` version in Debian stable does not have the
-"filter tests by tags" feature, which is very handy for running a subset of the
-tests. For this, we need to install `bats` from source. It's easy.
+Unfortunately, the latest `bats` version in Debian stable does not have the "filter tests by tags" feature, which is very handy for running a subset of the tests. For this, we need to install `bats` from source. It's easy.
 
 ```
 apt purge -y bats
@@ -62,28 +104,20 @@ cd bats-core
 sudo ./install.sh /usr/local
 ```
 
-### Setup Test Server
+#### Setup Test Server
 
-For many tests an actual server is needed, where apps can be deployed. You can
-either use a local one or a remote test server.
+For some tests an actual server is needed, where apps can be deployed. You can either use a local one or a remote test server. There is also a way to run or skip tests that require a remote server. This is covered below in the [filtering tests](#filter-tests_1) section.
 
-#### With remote test server
+##### Remote swarm
 
 ```
 export ABRA_TEST_DOMAIN="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
 ```
 
-`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com`
-which points to the same server so that the test suite can deploy apps freely.
-It's advised that you re-use the same server and therefore the same Traefik
-deployment for running your integration tests. The test suite does not deploy
-Traefik for you. Then you'll have more stable results.
+`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
 
-You probably don't want to run the entire test suite though, it takes a while.
-Try the following for starters.
-
-#### With local swarm
+##### Local swarm
 
 When running the test suite localy you need a running docker swarm setup:
 
@@ -110,32 +144,28 @@ bats -Tp tests/integration
 Or you can run a single test file:
 
 ```
-bats -Tp tests/integration/autocomplete.bats
+bats -Tp tests/integration/app_check.bats
 ```
 
 ### Tagging tests
 
-When a test actually deploys something to a server, we tag it with the following:
+When a test actually deploys something, we tag it as "slow". When the test requires public DNS, we use "dns". There may be more tags we write more tests.
 
 ```
-# bats test_tags=slow
+# bats test_tags=slow,dns
 @test "..." {
   ...
 }
 ```
 
-Then we can use [filters](#filter-tests) (see below) to pick out a subset of
-tests which do/do not use a live server. Feel free to come up with your own
-tags. See the `bats-core`
-[docs](https://bats-core.readthedocs.io/en/stable/writing-tests.html#tagging-tests)
-for more.
+Then we can use [filters](#filter-tests) (see below) to pick out a subset of tests which do/do not use a live server. Feel free to come up with your own tags. See the `bats-core` [docs](https://bats-core.readthedocs.io/en/stable/writing-tests.html#tagging-tests) for more.
 
 ### Filter tests
 
 You can run a specific file.
 
 ```
-bats -Tp tests/integration/autocomplete.bats
+bats -Tp tests/integration/app_check.bats
 ```
 
 For example, if you want to check that all `abra recipe ...` tests remain working.
@@ -153,21 +183,22 @@ bats -Tp tests/integration --filter "validate app argument"
 You can filter on tags.
 
 ```
-bats -Tp tests/integration --filter-tags "\!slow" # only fast tests
-bats -Tp tests/integration --filter-tags "slow"   # only slow tests
+bats -Tp tests/integration --filter-tags \!slow      # only fast tests
+bats -Tp tests/integration --filter-tags slow        # only slow tests
+bats -Tp tests/integration --filter-tags slow,\!dns  # slow but no DNS tests
 ```
 
 You can also only run the previously failed tests.
 
 ```
-bats -TP tests/integration --filter-status failed
+mkdir -p tests/integration/.bats/run-logs
+bats -Tp tests/integration                        # run tests
+bats -Tp tests/integration --filter-status failed # re-run only failed
 ```
 
 ### Debug tests
 
-If you're running into issues and want to debug stuff, you can pass `-x` to
-`bats` to trace all commands run in the test. You can add `echo '...' >&3`
-debug statements to your test to output stuff also.
+If you're running into issues and want to debug stuff, you can pass `-x` to `bats` to trace all commands run in the test. You can add `echo '...' >&3` debug statements to your test to output stuff also.
 
 ## Using the `abra` public API
 
@@ -208,11 +239,11 @@ func main() {
 
 Some tools that are making use of the API so far are:
 
-* [`kadabra`](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/cmd/kadabra/main.go)
+* [`kadabra`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/cmd/kadabra/main.go)
 
 ## Cross-compiling
 
-If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/coop-cloud/abra) and then:
+If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/toolshed/abra) and then:
 
 - enter the `abra` directory
 - run `git tag -l` to see the list of tags, choose the latest one
@@ -241,11 +272,11 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 ### Making a new release
 
 - Run the [integration test suite](#integration-tests) and the unit tests (`make test`) (takes a while!)
-- Change `ABRA_VERSION` in [`scripts/installer/installer`](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer) to match the new tag (use [semver](https://semver.org))
+- Change `ABRA_VERSION` in [`scripts/installer/installer`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer) to match the new tag (use [semver](https://semver.org))
 - Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-beta'`)
 - Make a new tag (e.g. `git tag -a x.y.z-beta`)
 - Push the new tag (e.g. `git push && git push --tags`)
-- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/coop-cloud/abra)
+- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/toolshed/abra)
 - Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
 - Check the release worked, (e.g. `abra upgrade; abra -v`)
 
@@ -253,12 +284,12 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 
 ### `godotenv`
 
-We maintain a fork of [godotenv](https://git.coopcloud.tech/coop-cloud/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/coop-cloud/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/coop-cloud/abra/pulls/391) for more.
+We maintain a fork of [godotenv](https://git.coopcloud.tech/toolshed/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/toolshed/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/toolshed/abra/pulls/391) for more.
 
 ### `docker/client`
 
-A number of modules in [pkg/upstream](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
+A number of modules in [pkg/upstream](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
 
 ### `github.com/schultz-is/passgen`
 
-Due to [`coop-cloud/organising#358`](https://git.coopcloud.tech/coop-cloud/organising/issues/358).
+Due to [`toolshed/organising#358`](https://git.coopcloud.tech/toolshed/organising/issues/358).

docs/abra/index.md

@@ -4,13 +4,15 @@ title: Abra
 
 <a href="https://github.com/egonelbre/gophers"><img align="right" width="250" src="https://github.com/egonelbre/gophers/raw/master/.thumb/sketch/adventure/poking-fire.png"/></a>
 
-[![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/abra/status.svg?ref=refs/heads/main)](https://build.coopcloud.tech/coop-cloud/abra)
-[![Go Report Card](https://goreportcard.com/badge/git.coopcloud.tech/coop-cloud/abra)](https://goreportcard.com/report/git.coopcloud.tech/coop-cloud/abra)
+[![Build Status](https://build.coopcloud.tech/api/badges/toolshed/abra/status.svg?ref=refs/heads/main)](https://build.coopcloud.tech/toolshed/abra)
+[![Go Report Card](https://goreportcard.com/badge/git.coopcloud.tech/toolshed/abra)](https://goreportcard.com/report/git.coopcloud.tech/toolshed/abra)
 [![Go Reference](https://pkg.go.dev/badge/coopcloud.tech/abra.svg)](https://pkg.go.dev/coopcloud.tech/abra)
 
 `abra` is the flagship client & command-line for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of operators and maintainers pleasant & convenient. It is libre software, written in Go and maintained and extended by the community :heart:
 
-Once you've got `abra` installed, you can start your own Co-op Cloud deployment. `abra` allows you to create, deploy and maintain libre software apps. It supports working with existing servers or can create new servers (supported providers: [Servers.coop](https://servers.coop/) & [Hetzner](https://hetzner.com)). It can also help you manage your DNS configuration (supported providers: [Gandi](https://gandi.net)).
+`abra` is the flagship client & command-line tool for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of [operators](https://docs.coopcloud.tech/operators/) and [maintainers](https://docs.coopcloud.tech/maintainers/) pleasant & convenient. It is libre software, written in [Go](https://go.dev) and maintained and extended by the community 💖
+
+Once you've got `abra` installed, you can start your own Co-op Cloud deployment.
 
 - [Install](/abra/install): You want to install `abra` :100:
 - [Quick start](/abra/quickstart): You're ready to get started using `abra` :muscle:

docs/abra/install.md

@@ -2,14 +2,40 @@
 title: Install
 ---
 
+## Installer script source
+
+You can view that [here](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer).
+
+## Installer prerequisites
+
+* `tar`
+* `wget`
+* `curl` (only if using `curl` method below)
+
 ## Stable release
 
+### Wget
+
+```
+wget -q -O - https://install.abra.coopcloud.tech | bash
+```
+
+### Curl
+
 ```
 curl https://install.abra.coopcloud.tech | bash
 ```
 
 ## Release candidate
 
+### Wget
+
+```
+wget -q -O - https://install.abra.coopcloud.tech | bash -s -- --rc
+```
+
+### Curl
+
 ```
 curl https://install.abra.coopcloud.tech | bash -s -- --rc
 ```
@@ -17,7 +43,7 @@ curl https://install.abra.coopcloud.tech | bash -s -- --rc
 ## Manual verification 
 
 You can download the `abra` binary yourself from the [releases
-page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the
+page](https://git.coopcloud.tech/toolshed/abra/releases) along with the
 `checksums.txt` file and verify it's integrity with the following command.
 
 ```bash
@@ -36,20 +62,16 @@ Otherwise, you downloaded a corrupted file and you should re-download it.
 
 Follow the guide [here](https://docs.coopcloud.tech/abra/hack/)
 
-## Installer script source
-
-You can view that [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).
-
 ## Using Docker
 
 ```
 docker run \
-	-v $HOME/.abra:/.abra \
-	git.coopcloud.tech/coop-cloud/abra app ls
+  -v $HOME/.abra:/.abra \
+  git.coopcloud.tech/toolshed/abra app ls
 ```
 
 !!! note
-	If you're using symlinks, e.g. for [sharing
-	`~/.abra`](/operators/handbook/#sharing-abra), add more `-v` options for each
-	directory you're symlinking to, e.g. `-v
-	$HOME/Projects/CoopCloud/apps:/home/user/Projects/CoopCloud/apps`
+    If you're using symlinks, e.g. for [sharing
+    `~/.abra`](/operators/handbook/#sharing-abra), add more `-v` options for
+    each directory you're symlinking to, e.g. `-v
+    $HOME/Projects/CoopCloud/apps:/home/user/Projects/CoopCloud/apps`

docs/abra/recipes.md

@@ -2,7 +2,7 @@
 title: Recipes
 ---
 
-_Recipes_ are what we call the configuration file used to deploy apps with our `abra` CLI tool. A longer explanation is in the [glossary](/glossary#recipe). Our _Catalogue_ is a web interface for exploring the currently available configurations, therefore which apps can be deployed. 
+_Recipes_ are what we call the configuration file used to deploy apps with our `abra` CLI tool. A longer explanation is in the [glossary](/intro/glossary#recipe). Our _Catalogue_ is a web interface for exploring the currently available configurations, therefore which apps can be deployed.
 
 ### Catalogue
 
@@ -84,7 +84,7 @@ Currently, recipe maintainers need to update the scores in this section manually
 ## Requesting Recipes
 
 If you'd like to see a new recipe packaged there are two options for you. First is to contribte one as a _Maintainer_ 
-The second option is to make a request on the [`recipes-wishlist`](https://git.coopcloud.tech/coop-cloud/recipes-wishlist) repository issue tracker.
+The second option is to make a request on the [`recipes-wishlist`](https://git.coopcloud.tech/toolshed/recipes-wishlist) repository issue tracker.
 
 If no one is around to help, you can always take a run at it yourself, go to the [Maintainers](/maintainers/) section to help you on your way.
 
@@ -100,7 +100,7 @@ If no one is around to help, you can always take a run at it yourself, go to the
 
     Don't feel up to the task? Open an issue in the `recipes-wishlist` repository
 
-    [Request Recipe](https://git.coopcloud.tech/coop-cloud/recipes-wishlist){ .md-button .md-button--primary }
+    [Request Recipe](https://git.coopcloud.tech/toolshed/recipes-wishlist){ .md-button .md-button--primary }
 
 </div>
 

docs/abra/trouble.md

@@ -4,7 +4,7 @@ title: Troubleshoot
 
 ## Where do I report `abra` bugs / feature requests?
 
-You can use [this issue tracker](https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose).
+You can use [this issue tracker](https://git.coopcloud.tech/toolshed/abra/issues/new).
 
 ## SSH connection issues?
 
@@ -63,23 +63,41 @@ We're still waiting for upstream patch which resovles this.
 
 ## Why can't `abra` support multiline in `.env` files?
 
-We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/coop-cloud/organising/issues/291) for more.
+We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/toolshed/organising/issues/291) for more.
 
 ## I need some feature from the old deprecated bash abra?
 
-There is an archive of the [old code here](https://git.coopcloud.tech/coop-cloud/abra-bash).
+There is an archive of the [old code here](https://git.coopcloud.tech/toolshed/abra-bash).
 
-You can install it alongside the [supported version of Abra](https://git.coopcloud.tech/coop-cloud/abra) by using these commands:
+You can install it alongside the [supported version of Abra](https://git.coopcloud.tech/toolshed/abra) by using these commands:
 
 ```bash
-git clone https://git.coopcloud.tech/coop-cloud/abra-bash ~/.abra/bash-src
+git clone https://git.coopcloud.tech/toolshed/abra-bash ~/.abra/bash-src
 ln -s ~/.abra/bash-src/abra ~/.local/bin/babra
 ```
 
 ## "Network not found" when deploying?
 
-This appears to be an upstream issue for which we can't do much in `abra` to solve. See [`coop-cloud/organising#420`](https://git.coopcloud.tech/coop-cloud/organising/issues/420) for more info. The work-around is to leave more time in between undeploy/deploy operations so the runtime can catch up.
+This appears to be an upstream issue for which we can't do much in `abra` to solve. See [`toolshed/organising#420`](https://git.coopcloud.tech/toolshed/organising/issues/420) for more info. The work-around is to leave more time in between undeploy/deploy operations so the runtime can catch up.
 
 ## Caller path in debug stacktrace doesn't exist
 
 Debug stacktrace currently begins with `/drone/` due to CI. Remove the initial `/drone/` and the path is relative to the abra project root.
+
+## "Failed to select default branch"
+
+General speaking, this error should not happen in the > v0.10.x `abra` version series. You can try upgrading if you're on an old version: `abra upgrade`.
+
+If you're really stuck, `rm -rf`'ing the relevant recipe repository and catalogue might do the trick.
+
+```
+$ abra app new foobar
+FATA[0000] unable to validate recipe: failed to select default branch in /root/.abra/catalogue
+$ rm -rf ~/.abra/recipes/foobar ~/.abra/catalogue
+```
+
+Otherwise, you can try manually cloning the recipe repository to the correct location.
+
+```
+$ git clone https://git.coopcloud.tech/coop-cloud/MyCoolRecipe.git ~/.abra/recipes
+```

docs/abra/upgrade.md

@@ -16,9 +16,122 @@ abra upgrade
 abra upgrade --rc
 ```
 
+### Manually
+
+You can also download a release manually. Go to the [releases
+page](https://git.coopcloud.tech/toolshed/abra/releases), download the release
+file, confirm the checksum and untar it.
+
+For example, for release candidate `0.10.0-rc1-beta` and `linux_amd64`.
+Download the release file.
+
+```
+wget https://git.coopcloud.tech/toolshed/abra/releases/download/0.10.0-rc1-beta/abra_0.10.0-rc1-beta_linux_amd64.tar.gz
+```
+
+Confirm the checksum.
+
+```
+wget https://git.coopcloud.tech/toolshed/abra/releases/download/0.10.0-rc1-beta/checksums.txt
+cat checksums.txt
+sha256sum abra_0.10.0-rc1-beta_linux_amd64.tar.gz
+```
+
+Untar the release.
+
+```
+tar -xvf abra_0.10.0-rc1-beta_linux_amd64.tar.gz
+```
+
+And test things work.
+
+```
+./abra -v
+```
+
 ## Migration guides
 
-> General release notes are [here](https://git.coopcloud.tech/coop-cloud/abra/releases/)
+> General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)
+
+### `0.9.x-beta` -> `0.10.x-beta`
+
+* `abra` will now write the app deployment version to the app env file
+  (`$ABRA_DIR/servers/<server>/<domain>.env`) against the `TYPE=/RECIPE=` env
+  var. This has a number of implications which are detailed in the [release
+  announcement post](https://coopcloud.tech/blog/new-year-status-update-25/).
+  The current `v0.9.x` series of `abra` will not be able to parse this version.
+  So, if you're testing the release candidate, you might to clean up your
+  `.env` files afterwards.
+
+* We have finally migrated from [`urfave/cli`](https://github.com/urfave/cli)
+  to [`spf13/cobra`](https://cobra.dev) as our command-line handling library.
+  This means we should (hopefully!) not have to deal with so many command-line
+  breaking changes in the future, e.g. how `--` is handled, how flags/args are
+  parsed and so on. We expect to maintain compatibility across this migration,
+  however you might run into something we didn't expect. Please do let us know.
+
+* `spf13/cobra` does not support "shorthand" flags with multiple characters.
+  So, the shorthard flags for `--git-name` / `--git-email` on `abra recipe new`
+  are now `-N` / `-e` respectively.
+
+* Auto-completion for `abra` is handled differently now. See `abra autocomplete
+  --help` for more. The full help output is available for each specific shell,
+  e.g. `abra autocomplete zsh --help`. It is now generated on the fly.
+
+* Several commands now make use of the `--chaos/-C` commands, such as `abra app
+  ps` and `abra app cp`. See `--help` for more.
+
+* `+ unstaged changes` is shown as `+U` in the overviews. This change was made
+  to support more compact display layouts. This marker will always be shown in
+  bold (**+U**) as a visual aid.
+
+* `abra` will no longer attempt to parse your `~/.ssh/config`. This means that
+  whatever you configure in your `~/.ssh/config` is the source of truth and
+  `abra` does not try to guess connection details. `abra` now *only* invokes
+  `/usr/bin/ssh`. This also means that `--problems/-p` goes away on `abra
+  server list`.
+
+* `abra app backup` / `abra app restore` now officially use
+  [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)! We
+  are still discussing how to handle this transition wrt. the original
+  `backup-bot`. Please see [this
+  ticket](https://git.coopcloud.tech/coop-cloud/backup-bot/issues/5) for more.
+
+* `--no-domain-checks` has been removed from `abra server add`. See
+  [`#631`](https://git.coopcloud.tech/toolshed/organising/issues/631) for more.
+
+* The output of `abra app ps` is less redundant in order to 1) reduce how much
+  horizontal width is required to render the table and 2) simplify the amount
+  of information shown. The `-w` option was also retired, you can use the
+  standard `watch` command, e.g. `watch abra app ps ...` to get the same
+  functionality.
+
+* Several overview screens have changed their layout. E.g. `abra app deploy`
+  now shows more (hopefully!) useful information. These changes have been made
+  to accomodate the work done around operator collaboration and stable
+  versioning.
+
+* `abra app deploy` / `upgrade` / `rollback` / etc. now show the deployment
+  progress, retry attempts and the healthcheck status.
+
+* Failed deployments will write output logs to file in `~/$ABRA_DIR/logs`.
+
+* `abra app errors` went away. It never really worked and was retired. You can
+  rely on `abra app logs` for the time being.
+
+* It's not possible to `--chaos/-C` on `upgrade` / `rollback`. See
+  [`#559`](https://git.coopcloud.tech/toolshed/organising/issues/559) for
+  more.
+
+* `main` will be chosen for new repositories created by `abra`. `abra` will
+  also attempt to clone the `main` branch first instead of the `master` branch.
+  The `master` branch is tried afterwards. This is mainly due to the fact that
+  the majority of our recipes use the `main` branch.
+
+* `abra recipe fetch` now accepts an `--all` flag to fetch all repositories.
+
+* It's now possible to set the character charset for a password. See
+  [`#521`](https://git.coopcloud.tech/toolshed/abra/issues/521) for more.
 
 ### `0.8.x-beta` -> `0.9.x-beta`
 
@@ -38,7 +151,7 @@ None at this time.
 
 - Secrets are now only generated by reading the recipe config, not the env
   vars. This should hopefully not affect you. If you're seeing weird behaviour,
-  please see [`#464`](https://git.coopcloud.tech/coop-cloud/organising/issues/464).
+  please see [`#464`](https://git.coopcloud.tech/toolshed/organising/issues/464).
 
 - There is a new linting rule for catching invalid tags in recipe versions.
   This is an seemingly unavoidable issue that requires some maintenance work.
@@ -72,13 +185,13 @@ None at this time.
 - Using `{{ .Domain }}` in recipe `.envrc.sample` files went away because it
   was portable enough. We revert to replacing e.g `gitea.example.com` with the
   domain. See
-  [`8fad34e`](https://git.coopcloud.tech/coop-cloud/abra/commit/8fad34e) for
+  [`8fad34e`](https://git.coopcloud.tech/toolshed/abra/commit/8fad34e) for
   more.
 
 - If your `abra.sh` scripts depend on `/bin/sh` and `/bin/bash` is available in
   the container then `/bin/bash` will be used from now on. `/bin/sh` is only
   now used if `/bin/bash` is not available. See
-  [`7f745ff`](https://git.coopcloud.tech/coop-cloud/abra/commit/7f745ff) for
+  [`7f745ff`](https://git.coopcloud.tech/toolshed/abra/commit/7f745ff) for
   more.
 
 ### `v0.4.x` -> `v0.5.x`

docs/federation/code-of-coop.md

@@ -0,0 +1,160 @@
+---
+title: Code of Co-operation
+---
+
+> Huge thanks to the folks at [Varia](https://varia.zone/) &
+> [LURK](https://lurk.org) who carefully prepared wonderful Code of Conduct
+> documents which we have adapted for our needs (with permission). See the
+> original documents [here](https://varia.zone/en/pages/code-of-conduct.html)
+> and [there](https://lurk.org/TOS.txt).
+
+Co-op Cloud is used by several communities coming from a variety of cultural,
+ethnic and professional backgrounds. We strive for to be welcoming to people of
+these various backgrounds and provide a non-toxic and harassment-free
+environment. 
+
+The Code of Conduct is a set of guidelines that help establish shared values
+and ensure that behaviour that may harm participants is avoided. 
+
+We acknowledge that we come from different backgrounds and all have certain
+biases and privileges. Therefore, this Code of Conduct cannot account for all
+the ways that people might feel excluded, unsafe or uncomfortable. We commit to
+open dialogues, and as such this Code of Conduct is never finished and should
+change whenever needed. We amend this document over time so it reflects the
+priorities and sensitivities of the community as it changes.
+
+It is a collective responsibility for all of us to enact the behaviour
+described in this document.
+
+## Expected behaviour
+
+We expect each other to:
+
+### Be considerate...
+
+...of each other, the space we enter, the Co-op Cloud community and the
+practices that it houses.
+
+### Be open and generous...
+
+...while trying not to make assumptions about others. This can include
+assumptions about identity, knowledge, experiences or preferred pronouns. Be
+generous with our time and our abilities, when we are able to. Help others, but
+ask first. There are many ways to contribute to a collective practice, which
+may differ from our individual ways.
+
+### Be respectful...
+
+...of different viewpoints and experiences. Respect physical and emotional
+boundaries. Be respectful of each others' limited time and energy. Take each
+other and each other's practices seriously. Acknowledge that this might lead to
+disagreement. However, disagreement is no excuse for poor manners.
+
+### Be responsible....
+
+...for the promises we make, meaning that we follow up on our commitments. We
+take responsibility for the good things we do, but also for the bad ones. We
+listen to and act upon respectful feedback. We correct ourselves when
+necessary, keeping in mind that the impact of our words and actions on other
+people doesn't always match our intent.
+
+### Be dedicated...
+
+...which means not letting the group happen to us, but making the group
+together. We participate in the group with self-respect and don't exhaust
+ourselves. This might mean saying how we feel, setting boundaries, being clear
+about our expectations. Nobody is expected to be perfect in this community.
+Asking questions early avoids problems later. Those who are asked should be
+responsive and helpful.
+
+### Be empathetic...
+
+..by actively listening to others and not dominating discussions. We give each
+other the chance to improve and let each other step up into positions of
+responsibility. We make room for others. We are aware of each other's feelings,
+provide support where necessary, and know when to step back. One's idea of
+caring may differ from how others want to be cared for. We ask to make sure
+that our actions are wanted.
+
+### Foster an inclusive environment...
+
+...by trying to create opportunities for others to express views, share skills
+and make other contributions. Being together is something we actively work on
+and requires negotiation. We recognize that not everyone has the same
+opportunities, therefore we must be sensitive to the context we operate in.
+There are implicit hierarchies that we can challenge, and we should strive to
+do so. When we organize something (projects, events, etc.), we think about how
+we can consider degrees of privilege, account for the needs of others, promote
+an activist stance and support other voices.
+
+## Unacceptable behaviour
+
+### No structural or personal discrimination
+
+Attitudes or comments promoting or reinforcing the oppression of any groups or
+people based on gender, gender identity and expression, race, ethnicity,
+nationality, sexuality, sexual orientation, religion, disability, mental
+illness, neurodiversity, personal appearance, physical appearance, body size,
+age, or class. Do not claim “reverse-isms”, for example “reverse racism”.
+
+### No harrassment
+
+Neither public nor private. Also no deliberate intimidation, stalking,
+following, harassing photography or recording, disruption of events,
+aggressive, slanderous, derogatory, or threatening comments online or in person
+and unwanted physical or electronic contact or sexual attention. No posting or
+disseminating libel, slander, or other disinformation.
+
+### No violation of privacy
+
+Namely publishing others’ private information, such as a physical or electronic
+address, without explicit permission. Do not take or publish photos or
+recordings of others after their request to not do so. Delete recordings if
+asked.
+
+### No unwelcome sexual conduct
+
+Including unwanted sexual language, imagery, actions, attention or advances.
+
+### No destructive behaviour
+
+Or any other conduct which could reasonably be considered inappropriate. This
+includes (but is not exclusive to) depictions of violence without content
+warnings, consistently and purposely derailing or disrupting conversations, or
+other behaviour that persistently disrupts the ability of others to engage in
+the group or space.
+
+## Intervention procedure
+
+**Immediate intervention (help is needed now!)**
+
+If you are feeling unsafe, you can immediately contact the Co-op Cloud members
+who are tasked with making sure the code of co-operation is respected.
+
+These contact people are members of Co-op Cloud who will do their best to help,
+or to find the correct assistance if relevant/necessary. Here is the list so
+far. If you would like to help in this task, please also feel free to volunteer
+to be a support member.
+
+> handle: `sordidwhiskey` contact:
+> [helo@coopcloud.tech](mailto:helo@coopcloud.tech) handle: `3wc` contact:
+> [helo@coopcloud.tech](mailto:helo@coopcloud.tech)
+
+For example, something happened during a still-ongoing online event and needs
+to be acted upon right away. Action is taken immediately when this violation of
+the code of co-operation is reported. This could involve removing an attendee
+from said event.
+
+## Non-immediate intervention (a situation that requires more time)
+
+Other violations need to be considered and consulted upon with more people or
+in a more measured way. For example: If you experience an ongoing pattern of
+harrassment; if you witness structurally unacceptable behaviour; if somebody
+keeps "accidentally" using discriminatory language, after being asked to stop.
+
+If you feel comfortable or able, discuss the issues with the involved parties
+before consulting a mediator. We prefer to constructively resolve disagreements
+together and work to right the wrong, when it is possible and safe to do so.
+However, if the problems still persist, those who are responsible for enforcing
+the code of co-operation can help you deal with these kinds of problems.
+Contact the members listed above. Information will be handled with sensitivity.

docs/federation/funding-applications/sovereign-tech-fund.md

@@ -26,7 +26,7 @@ Abra is a critical infrastructural resource because operators and recipe maintai
 
 ## Link to project repository
 
-[`git.coopcloud.tech/coop-cloud/abra`](https://git.coopcloud.tech/coop-cloud/abra)
+[`git.coopcloud.tech/toolshed/abra`](https://git.coopcloud.tech/toolshed/abra)
 
 ## Link to project website
 
@@ -90,9 +90,9 @@ The second is a new challenge in which we must implement larger scale enhancemen
 
 We currently categorise these two development trajectories under the following project boards:
 
-* [Critical fixes (15 tickets at time of writing)](https://git.coopcloud.tech/coop-cloud/organising/projects/24)
+* [Critical fixes (15 tickets at time of writing)](https://git.coopcloud.tech/toolshed/organising/projects/24)
 
-* [Medium/large enhancements (15 tickets at time of writing)](https://git.coopcloud.tech/coop-cloud/organising/projects/25)
+* [Medium/large enhancements (15 tickets at time of writing)](https://git.coopcloud.tech/toolshed/organising/projects/25)
 
 Abra has proven itself as a resilient toolset over 3 years of development and adoption. However, with the increase in scope of fixes and proposals for large scale changes, is at risk of falling behind and at worst, becoming an obstacle to day-to-day operations as the ecosystem of open source infrastructure management continues to change.
 

docs/federation/index.md

@@ -38,4 +38,10 @@ This is the public facing page where we publish all things federation in the ope
 
     [Tools We Use](/federation/tools){ .md-button .md-button--primary }
 
+- __Code of Co-operation__
+
+    Be excellent to each other 💝
+
+    [Read More](/federation/code-of-coop){ .md-button .md-button--primary }
+
 </div>

docs/federation/membership.md

@@ -4,15 +4,20 @@ 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
 
-| Name | Dues paid up? | Notes | Contact |
-| -------- | -------- | -------- |-------- |
-| Agaric | - | - | `@wolcen:matrix.org` |
-| Autonomic | - | - | `@3wc`, `@cas`, `@knoflook`, `@travvy`, `@aadil` |
-| Bonfire | - | - | `@mayel:matrix.org` + Ivan (`@cambriale:matrix.org`) |
-| Doop.coop | - | - | `@yusf:gottsnack.net` |
-| Klasse & Methode | - | - | `@p4u1_f4u1:matrix.org` |
-| Local IT | - | - | Philipp (`@yksflip:matrix.kaputt.cloud`) + `@moritz:matrix.local-it.org` |
-| Mirsal ™ | - | - | `@mirsal:1312.media` |
-| UTAW | - | - | `@javielico:matrix.org` |
-| [BeWater](https://bewater.contact) | Waiver | - | `@decentral1se` |
-| ruangrupa | - | - | Henry `@babystepper:matrix.org` |
+| Name      | Dues Paid | Notes    | Contact |
+| --------- | --------- | -------- |-------- |
+| Agaric    | - | - | `@wolcen:matrix.org` |
+| [Autonomic](https://autonomic.zone) | - | - | `@3wc`, `@cas`, `@knoflook`, `@travvy`, `@aadil` |
+| [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` |
+| [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` |
+| `@decentral1se` | Waiver | - | `@decentral1se` |
+| [ruangrupa](https://ruangrupa.id) | - | - | Henry `@babystepper:matrix.org` |
+| [Ammar](https://social.coop/@ammaratef45) | - | - | `@ammaratef45:matrix.org` |
+| [MIR](https://mirnet.org/) | ✅ | - | `@brooke:pub.solar` |
+| [Red Abya Yala](https://abyayala.sutty.nl/) | - | - | `@fauno:sutty.nl` |

docs/federation/minutes/2024-03-29.md

@@ -0,0 +1,125 @@
+---
+title: 2024-03-29
+---
+
+## Meta
+
+* Time: 29-03-2024
+* Present: d1, p4u1, mo
+* Call: https://vc.autistici.org/CoopCloudFederationMeeting
+
+## Agenda
+
+- checking in
+- abra release planning https://git.coopcloud.tech/toolshed/organising/issues/583
+- reforms to fedi process
+  - symptoms  
+    - eotl vote delayed weeks
+    - many members not paying dues, no waiver agreed
+    - vera / Flancia left all chats?
+  - proposals
+    - [define fedi member reponsibilities](https://git.coopcloud.tech/toolshed/organising/issues/579)
+    - exit criteria for fedi members
+    - delay x quorom decision making
+    - rolling "credit system" for doing work
+    
+## Notes
+
+### Checking in
+
+d1: last release was gnarly, was tired but now looking forward to coordinating new release
+
+mo: travelling, pretty busy, alakazam presentation/docs/feedback energies
+
+p4: release hell, good progress, happy to see automation for new release. backupbot spec is underway, to discuss soon...
+
+### Release planning
+
+Note about previous release: goreleaser refused to to release on a branch previously, so we reverted the backup changes and reverted the revert after the release
+
+#### Catalogue
+
+why catalogue?
+- advantage: git repository
+- disadvantage: overhead, CI/CD system, people don't understand it, several bugs
+
+proposal: rely on tags in the repository. clone everything to .abra/recipes/... pull tags locally on-the-fly.
+
+if i create a new version of a recipe, the catalogue is not even at all. it just looks locally. the update happens afterwards
+
+precomputing means saving resources later on
+
+With the operator collaboration topic, it will be possible to specificy an app recipe with a git location, it is then possible to skip the catalogue.
+https://git.coopcloud.tech/toolshed/organising/issues/533#issuecomment-19038
+
+recipes.coopcloud.tech (the Elm app) is reading the JSON
+
+in an ideal post-catalogue abra, you could just ref a git org where `RECIPE=<recipe>` would find `https://git.example.com/<org>/<recipe>` and even `RECIPE=<org>/<recipe>`
+
+Backwards compatiblibility will be key. For next next release 🎉
+
+#### Automation test suite
+
+Computing power from somewhere? Local-IT doing migration atm so not ideal timing. Maybe again after a month or so, can check-in again then.
+
+Can also ask Autonomic and/or whoever else feels like they can help.
+
+#### Cli Argument Handling
+
+https://git.coopcloud.tech/toolshed/organising/issues/581
+
+Upgrade to `urfave/cli` version 2 will enforce `abra app command command [command options] <domain> [<service>] <command> [-- <args>]`
+
+Maybe we need a poll to see how people are using it? `@mo` using the strict format anyway, `@d1` not minding, `@p4` in favour...
+
+adding a good/clear warning/error that if using e.g. `--chaos` on the end, it's not possible anymore...
+
+> How do you use flag options (e.g. `--chaos`) with Abra?
+> At the beginning: abra app deploy --chaos app.example.com
+> At the end: abra app deploy app.example.com --chaos
+
+> How annoyed will you be if, we enforce it at the beginning?
+> Not annoyed
+> Slighty annoyed
+> Very annoyed
+> If you are *annoyed, what can we do to help this process? e.g. docs, warning, etc.
+
+Decision vs. poll? It's not really a choice. the lib is broken / enforces this. its ambigous now and just causes issues / questions / confusion.
+
+Hack to re-order options transparently? Some pre-processor which would special case the `[-- ARGS]` for `abra app cmd`.
+
+Doing it one way is just clear for everyone.
+
+Plan: make proposal, get votes. if voted against, try to make new with adaptions / more work/money etc. but compromises with needs. (TODO: `@d1`)
+
+Btw emoji polls are actually broken for some clients 😱
+
+### Fedi process reforms
+
+https://git.coopcloud.tech/toolshed/organising/issues/579
+
+- pay yearly dues or get waiver (don't pay)
+- actively participate in voting
+- actively participate in monthly federation meetings. if you can't make it, please send your updates by text
+- agree to code of conduct
+
+exit criteria?
+
+- no yearly dues arragement
+- no/less voting/participation in meetings
+
+TODO: proposal, pass, check in with people in the "exit criteria" area, are they OK?
+
+### Goals of Federation?
+
+- what is the purpose of the fedi?
+- in relation to theory, ideology, strategy
+- Co-op Cloud Conf !!!
+- let's think about this and check back in
+
+### Next meeting
+
+`@mo` does next poll
+
+
+

docs/federation/minutes/2024-04-17.md

@@ -0,0 +1,73 @@
+---
+title: 2024-04-17
+---
+
+## Meta
+
+* Poll: https://poll.local-it.org/invite/Q828kjlYLNwW
+* Call: https://talk.local-it.org/rooms/nyy-z5y-yrh-sc2/join
+* Present: Local IT (moritz), EOTL (BaseBuilder, blu), BeWater(d1), Autonomic (Lai), Klasse & Methode (p4u1)
+
+## Agenda
+
+### First
+
+* Fixed monthly Federation meeting (3rd Mon, etc) `@basebuilder`
+* Project re-organisation (recipes, tools, fedi repos) `@d1`
+* Backup specification `@p4u1`
+
+### The Rest
+
+* Non-Federation tasks specific bounty / funding `@basebuilder`
+* Website and docs work to better showcase federation - `@kawaiipunk`
+    * https://git.coopcloud.tech/toolshed/organising/milestone/43
+* Recipe maintainence proposal - `@kawaiipunk`
+* "Hacking velocity = slow & money" (RE: recent fedi orga chat) `@d1`
+* Continuing budget 001 for meeting attendance, resolution 004 technically only covered 6 months to oct 2023 `@3wc` (but I won't be there)
+
+## Notes
+
+### Fixed monthly Federation meeting (3rd Mon, etc)
+
+Talked about it couple of times, back and forth.
+- People who want to do regular can do that
+- Other people can do polled meeting
+- Poll every month is time consuming
+- Timezones is an issue
+
+Poll options for meeting
+1. fix time/date every month
+1. fixed time/date with timezone wraparound (can be merged with 1. :)
+1. flexible every month (poll)
+1. fixed week with poll (day of week, crab.fit)
+
+> crab.fit - software with heatmap of availability
+
+### Project re-organisation (recipes, tools, fedi repos)
+
+Problem: All projects are under one organisation (coop-cloud). Abra has to do a lot of work to figure out what is a recipe repo and what not. This got fixed but made recipe generation really slow
+
+Proposal: 3 Organisations in gitea:
+- Recipes
+- Tools
+- Projects
+
+What to look out for:
+- Redirects (mainly for recipes)
+- SSH will break though -> could make a migration script for that?
+ 
+https://git.coopcloud.tech/toolshed/organising/milestone/45
+https://git.coopcloud.tech/toolshed/organising/issues/569
+
+Maybe "tools" / "projects" not needed, only "recipes" / "other".
+
+### Backup Specification
+
+Needing to write operators and matainers guide
+
+- [ ] should abra implement backup and restore or only provide an integration?
+- [ ] should we add a specification version?
+
+## Next Meeting
+
+* Who: ???

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/toolshed/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/toolshed/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/030-docs-naming-survey.md

@@ -0,0 +1,35 @@
+# Co-op Cloud resolution 030: docs / naming survey
+
+- Topic: Budget for a survey about the Co-op Cloud documentation 
+- Date: 2025-04-03
+- Deadline: 2025-04-17
+- Size: large
+
+## Summary
+
+Allocate up to €160 for the production and analysis of a survey to get feedback on the Co-op Cloud documentation (https://docs.coopcloud.tech), with a particular focus on the "operator" and "maintainer" names.
+
+Optional feedback on what docs example survey takers think we could benefit from observing and/or an optional description of how documentation can be improved in general will be present but not necessary acted on as part of this resolution.
+
+## Details
+
+- We've received some feedback that the key "Operators" and "Maintainers" names can be confusing, especially for non-native-English speakers
+- We're interested in getting wide input, from both the existing Co-op Cloud community, and the wider democratic tech space -- including from people unfamiliar with Co-op Cloud
+- As well as specific input on this naming question, it would also be useful to gather general feedback on the documentation, collecting suggestions on structure, clarity, format (including potential other media like screencasts, videos, or educational materials)
+
+Our rough plan / budget for this work is:
+- collecting information 1-2h
+- design survey 1-2h
+- distribute survey 1-2h
+- analyse survey 1-2h
+- 4-8 hours
+
+## Budget 0YY: Docs / naming survey
+
+* Budget amount: up to EUR 160
+
+* Who will implement this: 3wordchant & Ammar
+
+* When will the money be spent: in Q1 2025
+
+ * What is the money for: paying for work on a community survey about the Co-op Cloud documentation

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

@@ -0,0 +1,41 @@
+---
+title: "Resolution 031"
+---
+
+- Topic: Critical fixes amended process
+- Date: 2025-06-10
+- Deadline: 2025-06-24
+- Size: Medium
+
+### Summary
+
+This resolution proposes specific changes to [`R010: Budget 004: Critical
+fixes`](../passed/010.md). These changes are primarily intended to improve
+transparency and match our new organising methods.
+
+## Details
+
+Ammendments are as follows.
+
+1. "Confirmation from at least one other member": should be confirmed on the
+   issue itself and not in the Matrix chat. It is suggested to indicate this
+   when posting in the Matrix chat (aka "Please +1 on the issue itself").
+1. "A fix is deemed critical": when it is marked with the label "critical fix".
+   There is no specific project tracker for only these issues. This label can
+   be re-used across repositories also.
+
+### R010 in full
+
+> We propose to have a standing budget of 10 hrs / month available for fixes in Abra, Co-op Cloud recipes and other critical tools (e.g. recipes.coopcloud.tech) in the Co-op Cloud ecosystem.
+>
+> A fix is deemed critical when it is listed on this toolshed/organising board:
+>
+> > https://git.coopcloud.tech/toolshed/organising/projects/24
+>
+> This board is collectively gardened by Co-op Cloud participants (both federation members and not). The process for adding a ticket to the board requires getting confirmation from at least one other member of the federation.
+>
+> This budget can be claimed by any volunteer who would like to develop the fix. If the volunteer is not a Co-op Cloud federation member, they must first be "vouched for" by a federation member. This is an informal process which can be arranged via the Matrix chat. This aims to assure agreement on timing and what the fix should contain beforehand.
+>
+> Fixes can be claimed by assiging yourself to the ticket. If within 1 week there is no updates on the ticket, another volunteer can propose to take over. This process is also informal: please @ the original volunteer and give some reasonable time for them to reply (suggested: 1 day).
+>
+> If the fix is urgent and things need to move faster, please state so on the ticket. Please consult with at least one other member of the federation to confirm that there is indeed agreement on the urgency of the fix.

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/010.md

@@ -11,9 +11,9 @@ title: "Resolution 010"
 
 We propose to have a standing budget of 10 hrs / month available for fixes in Abra, Co-op Cloud recipes and other critical tools (e.g. recipes.coopcloud.tech) in the Co-op Cloud ecosystem.
 
-A fix is deemed critial when it is listed on this coop-cloud/organising board:
+A fix is deemed critical when it is listed on this toolshed/organising board:
 
-> https://git.coopcloud.tech/coop-cloud/organising/projects/24
+> https://git.coopcloud.tech/toolshed/organising/projects/24
 
 This board is collectively gardened by Co-op Cloud participants (both federation members and not). The process for adding a ticket to the board requires getting confirmation from at least one other member of the federation.
 

docs/federation/resolutions/passed/012.md

@@ -19,7 +19,7 @@ It's time to build a robust Abra integration test suite which can help us stop r
 
 References so far:
 - [3wc & myself (d1) have had a planning meeting](https://pad.autonomic.zone/kdLrPXMSSb2TZezCBhdYtw?edit)
-- [The first PR and proof of concept has landed in Abra](https://git.coopcloud.tech/coop-cloud/abra/pulls/347)
+- [The first PR and proof of concept has landed in Abra](https://git.coopcloud.tech/toolshed/abra/pulls/347)
 - [Initial documentation has been written](https://docs.coopcloud.tech/abra/hack/#integration-tests)
 
 With some further experimentation, I'm relatively confident that this approach will allow us to implement an integration test suite which covers the majority of the Abra functionality. It's *a lot* of work. I'm estimating this to come in at 30 hours of work.

docs/federation/resolutions/passed/014.md

@@ -22,14 +22,14 @@ estimating: small (1-3 hours), medium (3-8 hours), large (8-15 hours) & order is
 
 | NAME | estimation |
 | ---- | ----- |
-| [#535 Comment parsing and modifiers](https://git.coopcloud.tech/coop-cloud/organising/issues/535) | Large |
-| [#519 abra app new `[<recipe>]` `[<version>]`](https://git.coopcloud.tech/coop-cloud/organising/issues/519) | Medium |
-| [#518 Abra fails silently if required image doesn't exist](https://git.coopcloud.tech/coop-cloud/organising/issues/518) | Medium |
-| [#527 abra catalogue generate `<recipe name>` ignores the specified recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/527) | Small |
-| [#509 abra app remove could wait until volume is not in use](https://git.coopcloud.tech/coop-cloud/organising/issues/509) | Medium |
-| [#530 abra recipe fetch can only fetch a single recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/530) | Medium |
-| [#525 prevent abra app cp from applying file permissions.](https://git.coopcloud.tech/coop-cloud/organising/issues/525) | Medium |
-| [#537 Fix the operators tutorial](https://git.coopcloud.tech/coop-cloud/organising/issues/537) | Medium |
+| [#535 Comment parsing and modifiers](https://git.coopcloud.tech/toolshed/organising/issues/535) | Large |
+| [#519 abra app new `[<recipe>]` `[<version>]`](https://git.coopcloud.tech/toolshed/organising/issues/519) | Medium |
+| [#518 Abra fails silently if required image doesn't exist](https://git.coopcloud.tech/toolshed/organising/issues/518) | Medium |
+| [#527 abra catalogue generate `<recipe name>` ignores the specified recipe](https://git.coopcloud.tech/toolshed/organising/issues/527) | Small |
+| [#509 abra app remove could wait until volume is not in use](https://git.coopcloud.tech/toolshed/organising/issues/509) | Medium |
+| [#530 abra recipe fetch can only fetch a single recipe](https://git.coopcloud.tech/toolshed/organising/issues/530) | Medium |
+| [#525 prevent abra app cp from applying file permissions.](https://git.coopcloud.tech/toolshed/organising/issues/525) | Medium |
+| [#537 Fix the operators tutorial](https://git.coopcloud.tech/toolshed/organising/issues/537) | Medium |
 
 Estimation: best case: (8 * 1) + (3 * 6) + (1 * 1) = 27 hours
 Estimation: worst case: (15 * 1) + (8 * 6) + (1 * 3) = 73 hours

docs/federation/resolutions/passed/019.md

@@ -4,7 +4,7 @@ title: "Resolution 019"
 
 - Topic: Karrot joins the Co-op Cloud Federation
 - Date: 25-03-24
-- Deadline: 25-04-2024
+- Deadline: 08-04-2024
 - Size: Large
 
 ### Summary
@@ -12,10 +12,11 @@ title: "Resolution 019"
 > [Karrot](https://karrot.world) / [Docs](https://docs.karrot.world)
 
 [@nicksellen](https://git.coopcloud.tech/nicksellen) is a Karrot Team member and has:
-- used Co-op Cloud for https://bath.social
-- supported Foodsharing Luxembourg to self-host Karrot using Co-op Cloud
-- participated in https://matrix.to/#/#coopcloud-tech:autonomic.zone chat
-- some small contributions/fixes/bug reports for some Co-op Cloud stuff
+
+- Used Co-op Cloud for [bath.social](https://bath.social)
+- Supported Foodsharing Luxembourg to self-host Karrot using Co-op Cloud
+- Participated in [`#coopcloud-tech:autonomic.zone`](https://matrix.to/#/#coopcloud-tech:autonomic.zone) chat
+- Some small contributions/fixes/bug reports for some Co-op Cloud stuff
 
 ### Details
 

docs/federation/resolutions/passed/020.md

@@ -0,0 +1,48 @@
+---
+title: "Resolution 020"
+---
+
+- Topic: Budget 10: Abra integration suite automation
+- Date: 04-04-2024
+- Deadline: 18-04-2024
+- Size: Large
+
+### Summary
+
+Motivated by the collective release planning:
+[`#583`](https://git.coopcloud.tech/toolshed/organising/issues/583) under
+"Automate Integration Test Suite".
+
+The latest `abra` release (`0.9.x`) was heavily delayed due to several issues.
+One of those was the need to fix the integration test suite which wasn't run in
+some time. Many breakages had crept into the test suite over time. This can
+avoided in the future by automating the running of the integration test suite.
+
+This proposal describes a way to do this and includes a budget for doing so.
+
+### Details (Budget 10)
+
+The `abra` test suite takes around 1.30 hrs to run on a modest machine.
+Therefore, we propose to run it only once daily. Some parts of the tests are
+slow, fast and only a few require public DNS. This means we can break up the
+tests and run them in separate "builds" to speed things up. This involves some
+research & experimentation.
+
+A server has been provided by `@mirsal` on donation (💘). This machine will be
+be wiped clean each day (`docker <command> prune ....`) and will have the usual
+DNS machinery attached to it, e.g. `int.coopcloud.tech`, `*.int.coopcloud.tech`.
+
+Once that is all wired up, we can implement the CI/CD configuration to make the
+test suite run automatically once a day. This will be triggered via the
+`.drone.yml` in the `abra` Git repository.
+
+Budget details:
+
+| Item | Cost | Who? |
+| ---- | ---- | ---- |
+| Server | Free (on donation) | `@mirsal` |
+| Server setup & docs | 1 hour | `@d1` |
+| R & D for breaking up tests | 5 hours | `@d1` | 
+| Implementing CI/CD configs | 10 hours | `@d1` |
+
+**Total: 16 hrs * 20 EUR = 320 EUR**

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/toolshed/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/toolshed/abra/pulls/404) [attempts](https://git.coopcloud.tech/toolshed/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/federation/resolutions/passed/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 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 metdata on all recipes. Rename 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 maintainers 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/passed/026.md

@@ -0,0 +1,28 @@
+---
+title: "Resolution 026"
+---
+
+- Topic: Budget 014: Backpay for `v0.10.x` abra release work
+- Date: 08-01-2025
+- Deadline: 22-01-2025
+- Size: Large
+
+### Summary
+
+`@decentral1se` had spoons and cycles from roughly December 27th 2024 - January 5th January to make the final push of development work to get the new `abra` release out.
+
+See the **WIP** [migration docs](https://docs.coopcloud.tech/abra/upgrade/#09x-beta-010x-beta) and [release blogpost](https://pad.local-it.org/G1TOcidEQtyArJU9gI0SDw?both#New-abra-release-candidate) for more information. TLDR; we have a release candidate that you can test today.
+
+In this resolution, budget is being asked to *retroactively* cover this development work as "backpay".
+
+### Details (Budget 014)
+
+An [invoice was submitted already](https://opencollective.com/coop-cloud/expenses/234126) on our Open Collective based on a "fuzzy consensus" within the Co-op Cloud Federation chat. However, on reflection, concerns were raised that it would be better to follow our agreed decision making process and submit a resolution to vote.
+
+There are 15 hours that are covered by [`R021`](https://docs.coopcloud.tech/federation/resolutions/passed/021/). However, the development of this work ran over by 3 hours. The remaining development work took 32 hours. The details of the specific tickets are on the [Open Collective invoice](https://opencollective.com/coop-cloud/expenses/234126). That brings the total amount of hours to 52.
+
+#### Budget
+
+`@decentral1se` has *already* carried out this work.
+
+Proposed budget of 52 hrs * 20 EUR: 1040 EUR

docs/federation/resolutions/passed/027.md

@@ -0,0 +1,22 @@
+---
+title: "Resolution 027"
+---
+
+- Topic: MIR joins the Co-op Cloud Federation
+- Date: 18-01-25
+- Deadline: 31-01-25
+- Size: Large
+
+### Summary
+
+[MIR](https://mirnet.org) would like to the join the Co-op Cloud Federation.
+Several members of the project are involved in hacking recipes, there has been
+personal contact via a call with `@decentral1se` (also several federation
+members have expressed enthusiasm for them joining) and they have ambitions to
+co-develop Co-op Cloud.
+
+### Details
+
+MIR can contribute fees at this time:
+
+`@decentral1se` is happy to vouch 💖

docs/federation/resolutions/passed/028.md

@@ -0,0 +1,15 @@
+# Resolution 028: Red Abya Yala joins the Co-op Cloud Federation
+
+- Topic: Red Abya Yala joins the Co-op Cloud Federation
+- Date: 16-01-2025
+- Deadline: 30-01-2025
+- Size: large
+
+## Summary
+
+Red Abya Yala is the network of Coopcloud nodes from Escuela Común.  It has facilitated Coopcloud workshops during Escuela Común and some members have contributed to recipes.
+
+Representative: `@fauno:sutty.nl`
+
+* https://abyayala.sutty.nl/
+* https://escuelacomun.yanapak.org/

docs/federation/resolutions/passed/029.md

@@ -0,0 +1,74 @@
+# Resolution 29 Budget 14: Federation Radmin
+
+- Topic: Establish Budget 14, to pay for up to 12 hours a month of "radmin" (radical administration) work, to help the federation run smoother, for an initial period of 12 months.
+- Date: 05-04-2025
+- Deadline: 19-04-2025
+- Size: Large
+
+## Summary
+
+Experience shows that solid administration is the basis for effective self-organisation. We call this "radmin" (radical admin) because this admin work acts as motor which boosts our self-organisation and coordination potential.
+
+We are in a unique position to discuss and implement a financial model which can meet our vision of sustainability based on our democratic structure and decision making process. We believe that it is more important than ever to make software project governance work without dictators. This role plays a critical role in making that possible.
+
+Autonomic has been carrying out the financial administration so far but cannot continue to do this due to low capacity. No other federation member can pick up this work at this time. To make progress, we propose to create a strict mandate for a paid radmin role which will be published as an open call. Anyone can fill this role, claim the budget and support the federation.
+
+Federation members will decide on who fills the role based on an evaluation of the candidates. The open call draft will specify exact details once this decision is approved and will be presented to federation members. The open call will be agreed upon by discussion with fedi members feedback, not decision making.
+
+## Details
+
+### Mandate
+
+* Up to 12 hours a month @ 20 EUR per hour based on the currently available federation membership dues
+* Establishing a financial bookkeeping structure for the federation with associated documentation
+* Instigating handover from Autonomic finance admin
+* Leading a discussion which establishes a shared understanding of what financial sustainability means for the federation today with associated documentation
+* Designing and implementing a new federation membership fees system which supports financial sustainability and is passed with a large decision
+* Contributing to the Co-op Cloud [wiki](https://docs.coopcloud.tech) (training provided)
+* Making sure invoices are submitted correctly and approving them via the Co-op Cloud Open Collective (OC)
+* Managing budgets and facilitating timetracking against those budgets (e.g. https://kimai.coopcloud.tech)
+* Herding cats
+* Timetrack to be done on the activity level via our [Kimai](https://kimai.coopcloud.tech) for accountability
+* Invoicing for your time each month to the Co-op Cloud OC
+
+### Extension
+
+**IMPORTANT**: Extensions to this mandate can **only** be established through official decision making process. 
+
+We expect that this radmin work will continue to be necessary as long as the federation exists, so it can be a stable source of (some) income in the future.
+
+### Duration
+
+The term duration of this role is 1 year with a start date which will be decided in conversation with the contractor.
+
+### Recall
+
+The term of duration can be recalled by the federation via established decision making channels (large resolution) if issues cannot be resolved through dialogue and constructive feedback.
+
+In the event of recall, there will be a collaborative feedback session between the federation and the contractor with the implementors of this propsal.
+
+### Buddy system
+
+Implementors of this resolution commit to a fixed monthly meeting, date/time to be determined, to check in and discuss challenges, progress, plans etc. This could preferably occur during the [Kite-flying hours (R024)](https://docs.coopcloud.tech/federation/resolutions/passed/024/) unless privacy needs require otherwise.
+
+This is an important accountability structure which is not aimed to surveil the contractor but ensure that both the federation and the radmin role are working well together and where things can be improved, take action together to resolve it.
+
+### Open call
+
+An open call is to be publised based on this proposal and shared openly. The open call will be presented as a draft to federation members before publishing. Exact details of the process, evaluation, start/end date etc. will be included in the text.
+
+## Budget 014
+
+The role is paid primarily from the current membership fees, as decided on [R002](https://docs.coopcloud.tech/federation/resolutions/passed/002/). The hope is that by filling this role, we can increase this budget through the design and implementation of a more sustainable financial model for the federation (see mandate above).
+
+- Budget amount:
+    - 250 EUR per month (hours for contractor)
+    - 40 EUR per month (hours for implementors / buddys)
+    - **Total**: 290 EUR per month
+- Who will implement this: decentral1se, kawaiipunk (Autonomic)
+- When will the money be spent: On an ongoing basis
+- What is the money for: Paying the working hours of whoever fills the role
+
+## Legal
+
+The contractor must function as a freelancer contractor and is responsible for their own invoices and taxes. Currently the Co-op Cloud project is stewarded by Autonomic Co-operative Limited and does not have it's own legal entity, so the freelance contract will be with Autonomic Co-operative Limited.

docs/federation/resolutions/stalled/013.md

@@ -6,7 +6,7 @@ title: "Resolution 013"
 
       This resolution has been amended! The main change was to remove automatic
       git synchronisation; please see [the file
-      history](https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/commits/branch/main/docs/federation/resolutions/in-progress/013.md) for a full run-down.
+      history](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/commits/branch/main/docs/federation/resolutions/in-progress/013.md) for a full run-down.
 
 - Budget 007: Operator sync
 - Date: 2024-01-??
@@ -15,7 +15,7 @@ title: "Resolution 013"
 
 ### Summary
 
-As highlighted in several tickets (e.g. [`#434`](https://git.coopcloud.tech/coop-cloud/organising/issues/434), [`#467`](https://git.coopcloud.tech/coop-cloud/organising/issues/467)), several operators working together on the same server routinely run into deployment instability. This is due to the fact that we do not store the deployment version of the apps.
+As highlighted in several tickets (e.g. [`#434`](https://git.coopcloud.tech/toolshed/organising/issues/434), [`#467`](https://git.coopcloud.tech/toolshed/organising/issues/467)), several operators working together on the same server routinely run into deployment instability. This is due to the fact that we do not store the deployment version of the apps.
 
 With this proposal, we would like to address the synchronisation of app deployment versions. This is being called "Operator sync". What follows is the design proposal which has already received feedback from operators on [this pad](https://pad.riseup.net/p/IebZQkpe3OOpYyVT8f1j-keep).
 

docs/index.md

@@ -4,9 +4,11 @@ title: Introduction
 
 ## Who is this for?
 
-Welcome to the Co-op Cloud documentation 🥳
+Welcome to the Co-op Cloud documentation 👋
 
-The documentation is aimed at a technical audience: tech co-ops, collectives and individuals who are curious about Co-op Cloud or are already running and managing Co-op Cloud deployments.
+In the spirit of transparency and to avoid confusion, we would like to begin with the explanation that this documentation is aimed at a **technical audience**.
+
+We have written this with the following groups in mind: tech co-ops, collectives and individuals who have familiarity with system administration and libre software communities and are curious about Co-op Cloud or are already running and managing Co-op Cloud deployments.
 
 A more general public may still find these pages useful but if you're just looking for a quick overview of the project from a less technical perspective, you can take a look at [coopcloud.tech](https://coopcloud.tech).
 
@@ -16,18 +18,18 @@ We'd be happy to hear feedback about our documentation, if it was helpful, what
 
 !!! danger "Here be dragons"
 
-    This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/get-involved/).
+    This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/intro/get-involved/).
 
 - [Operators guide](/operators/): You run a Co-op Cloud based deployment or want to do so :computer:
 
 - [Maintainers guide](/maintainers/): You maintain recipes and ensure things run smoothly for operators :tools:
 
-- [Organisers guide](/organisers): You run meetings, write guidelines & shape our democratic process :fist:
+- [Organisers guide](/federation/organisers): You run meetings, write guidelines & shape our democratic process :fist:
 
 - [Recipes](/abra/recipes/): You want to know what recipes are packaged so you can deploy them as apps :nerd:
 
 - [Abra](/abra): You want to install the command-line client and hack the planet :unicorn:
 
-- [Get involved](/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
+- [Get involved](/intro/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
 
-- [Glossary](/glossary/): You'd like clarification about project terminology :book:
+- [Glossary](/intro/glossary/): You'd like clarification about project terminology :book:

docs/intro/bikemap.md

@@ -6,4 +6,4 @@ title: Bike map
 
 - We are working towards a stable `1.0.0` release.
 
-- What we're currently working on is listed on this issue tracker: [`coop-cloud/organising`](https://git.coopcloud.tech/coop-cloud/organising/issues).
+- What we're currently working on is listed on this issue tracker: [`toolshed/projects`](https://git.coopcloud.tech/toolshed/-/projects).

docs/intro/faq.md

@@ -8,12 +8,10 @@ Co-op Cloud aims to make hosting libre software apps simple for small service pr
 
 ## Who is behind the project?
 
-The project was started by workers at [Autonomic](https://autonomic.zone/) which
-is a [worker-owned co-operative](https://en.wikipedia.org/wiki/Worker_cooperative) who provides
-technologies and infrastructure to empower users to make a positive impact on
-the world. Numerous other like minded co-ops have since joined our
-[Federation](/federation/) and rely *Co-op Cloud* in production.
-
+The project was initiated by workers at [Autonomic](https://autonomic.zone/), a
+[worker-owned co-operative](https://en.wikipedia.org/wiki/Worker_cooperative).
+Numerous other like minded co-ops have since joined the
+[Federation](/federation/) and rely on *Co-op Cloud* in production.
 
 ## Why Co-op Cloud?
 
@@ -53,7 +51,7 @@ The core technologies of Co-op Cloud are libre software and enjoy wide adoption
 - [Containers](#why-containers)
 - [Compose specification](#why-docker-compose)
 - [Docker swarm](#why-docker-swarm)
-- [Abra command-line tool](https://git.autonomic.zone/coop-cloud/abra)
+- [Abra command-line tool](https://git.autonomic.zone/toolshed/abra)
 
 ## Why containers?
 
@@ -160,7 +158,7 @@ Yes! Horizontal scaling is one of the ways Co-op Cloud can really shine. `abra`
 
 ## Why only x86 support?
 
-We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.coopcloud.tech/coop-cloud/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](/intro/contact/).
+We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.coopcloud.tech/toolshed/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](/intro/contact/).
 
 Update: [Can I run Co-op Cloud on ARM?](/operators/handbook/#can-i-run-co-op-cloud-on-arm)
 
@@ -175,3 +173,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/get-involved.md

@@ -4,19 +4,19 @@ title: Get Involved
 
 ## Overview
 
-> :trumpet: **You don't have to be a programmer to contribute to this project!** :trumpet:
+> 📢 **You don't have to be a programmer to contribute to this project** 📢
 
-Firstly, come say hello in our [chat room](/intro/contact/) if you'd like to help out or are interested to learn how :wave:
+Firstly, come say hello in our [chat room](/intro/contact/) if you'd like to help out or are interested to learn how 👋
 
 We are happy to have designers, critical thinkers, artists, hackers, documenters, etc. involved in this project! There is a lot of work to do, if you find this project interesting, we want to have you working with us.
 
 There are a number of "roles" such as "operator", "maintainer", "organiser" which we've tried to come up with to make it more clear how you can relate to the project and how you can find ways to be involved which suit your interests. If you don't fit one of these roles, that is fine.
 
-We have [an irregular online check-in](/organisers/handbook/#kite-flying-hours) for contributors of this project to let each other know what we're working on, how much time we've spent on it and how to coordinate further work.
+We have [an irregular online check-in](/federation/organisers/#kite-flying-hours) for contributors of this project to let each other know what we're working on, how much time we've spent on it and how to coordinate further work.
 
 We have a [status page](/intro/bikemap) showing what we are aiming to achieve in the near future. That gives a good overview of where we're going together.
 
-We use [issue trackers](https://git.coopcloud.tech/coop-cloud/organising/issues) and [project boards](https://git.coopcloud.tech/coop-cloud/organising/projects) to keep track of what we're working on right now. We collectively review these, to keep track of our time spent vs. budget available.
+We use [issue trackers](https://git.coopcloud.tech/coop-cloud/organising/issues) and [project boards](https://git.coopcloud.tech/toolshed/projects) to keep track of what we're working on right now. We collectively review these, to keep track of our time spent vs. budget available.
 
 ## Compensation
 

docs/intro/glossary.md

@@ -4,7 +4,7 @@ title: Glossary
 
 ## Abra
 
-A command-line tool that has been developed specifically in the context of the Co-op Cloud project for the purpose of making day-to-day operations for [operators](/operators/) and [maintainers](/maintainers/) as convenient as possible. It is libre software, written in [Go](https://go.dev/) and maintained and extended by the community. You can find the source [here](https://git.coopcloud.tech/coop-cloud/abra).
+A command-line tool that has been developed specifically in the context of the Co-op Cloud project for the purpose of making day-to-day operations for [operators](/operators/) and [maintainers](/maintainers/) as convenient as possible. It is libre software, written in [Go](https://go.dev/) and maintained and extended by the community. You can find the source [here](https://git.coopcloud.tech/toolshed/abra).
 
 ## App
 

docs/intro/inspirations.md

@@ -0,0 +1,8 @@
+---
+title: Inspirations
+---
+
+* [CoopCycle](https://coopcycle.org/en/)
+* [Dmytri Kleiner: "You can't code away their wealth"](https://yewtu.be/watch?v=FEU632_Em3g)
+* [The Telekommunist Manifesto](https://www.networkcultures.org/_uploads/%233notebook_telekommunist.pdf)
+* [Free Software Syndicalism](https://oxygen.offdem.net/pub/synware-free-software-syndicates)

docs/intro/managed.md

@@ -4,10 +4,14 @@ title: Managed hosting
 
 !!! danger "We're still working this out, you can help too!"
 
-    If you're a co-operative or a tech collective who wants to appear on this list, please [get in touch](/intro/contact/)! We want to expand the number of service providers using the Co-op Cloud so that project is more widely available to end-users and organisations who can influence the direction and co-fund the development.
+    If you're a co-operative or a tech collective who wants to appear on this
+    list, please [get in touch](/intro/contact/)! We want to expand the number
+    of service providers using Co-op Cloud so that project is more widely
+    available to end-users and organisations who can influence the direction
+    and co-fund the development.
 
-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.
+*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))
-- [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))
+- [Autonomic Co-op](https://autonomic.zone) (contact: [`helo@autonomic.zone`](mailto:boop@autonomic.zone))
+- [makeITsocial](https://makeitsocial.net) (managed hosting, see [price calculator](https://makeitsocial.net/kolli-cloud/))
+- [Local-IT](https://local-it.org/) ([selfhosting](https://wiki.local-it.org/s/kollicloud-wiki/doc/selfhosting-guide-1xZJt8UIha) & cooperative hosting, contact: [`info@local-it.org`](mailto:info@local-it.org))

docs/intro/strategy.md

@@ -6,17 +6,23 @@ From our experiences working and organising as Autonomic, the tech co-op who [in
 
 ## Technological Saviors?
 
-The urgency for providing an alternative comes out of the understanding that the concentration of our digital lives within the private sphere of corporate providers (e.g. [GAFAM](https://degooglisons-internet.org/en/)) represents a loss of freedom due to the threat to our privacy and self-determination through surveillance and monopolisation.
+The urgency to build an alternative to ["corporate clouds"](https://2023.transmediale.de/en/event/counter-cloud-strategies) is based on an analysis which we summarise briefly here.
 
-As a movement, we cannot compete with corporate providers in terms of cost and scale. Their network effects and available capital means that no one project, product or organisation can create the required shift to a more widespread public interest technology.
+We begin with the monopolisation of our digital lives, the stranglehold of corporate control (aka [GAFAM](https://degooglisons-internet.org/en/)), which represents a grave threat to our collective freedom, our societies and our hopes for a good life on planet earth.
 
-> Technology alone will not save us
->
-> Simply deploying libre software is not enough. 
+We acknowledge the vast accumulation of network effects and resources accrued by these monopolies. This is the basis of our understanding that no single project, "product" or organisation can create the required shift to a more widespread public interest technology.
 
-Our strategy is to mutualise our resources to facilitate this shift. _Co-op Cloud_ is an attempt to create a new shared resource - an open and democratically managed, open standards based, copyleft licensed, libre software infrastructure project.
+When we say public interest technology, we mean a technology which is not built in the service of monopoly. We are speaking of a technology which emerges from elements of democracy: bottom-up decision making, social need, community ownership and ecological thinking. Our aspiration is a technology which is built in the service of social justice, equality and collective freedom.
 
-From this base, we can focus on the urgent and necessary social organising work that goes beyond the technical question.
+Our strategy is to mutualise our resources to facilitate this shift. We harbour no illusions: technology alone will not "save us" and simply deploying libre software is not enough. We do not operate in a bubble and do not wish to remain contained within a subculture.
+
+We can say that _Co-op Cloud_ is a libre software infrastructure project. It is based on open standards, is copyleft licensed and is open and democratically managed.
+
+We can also say that _Co-op Cloud_ is a social movement of hosters, hackers, technologists and their allies who defend a vision of collective self-management.
+
+We are committed to an organisational form which allows us to accumulate knowledge, solidarity, experience and resources. We claim a rich history of grassroots social resistance, direct action and struggle for collective liberation.
+
+We propose to go beyond a reductive technological vision of social change.
 
 ## The Moving Parts
 
@@ -24,9 +30,9 @@ _Co-op Cloud_ is made up of a few simple, composable pieces. The system does not
 
 ``` mermaid
 graph LR
-  A[Libre Software\n Apps] --> B{Recipe Packaging};
-  B --> C[CLI Tool];
-  C --> D[Container\n Orchestrator];
+  A[Libre software apps] --> B{Recipe packaging};
+  B --> C[Command-line tool];
+  C --> D[Container orchestrator];
 ```
 
 Once you [grok](https://en.wikipedia.org/wiki/Grok) this, you grok the moving parts of the entire project. You can then move on to [deploying your first app](/operators/tutorial/#deploy-your-first-app).

docs/maintainers/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.
 
@@ -313,7 +313,7 @@ index 1618ef5..6cd754d 100644
 
 !!! warning "Here be versioning dragons"
 
-    `abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/coop-cloud/tagcmp) for more info on how we implement image parsing.
+    `abra` doesn't understand all image tags unfortunately. There are limitations which we're still running into. You can pass `-a` to have `abra` list all available image tags from the upstream repository and then make a choice manually. See [`tagcmp`](https://git.coopcloud.tech/toolshed/tagcmp) for more info on how we implement image parsing.
 
 Next, we need to update the label in the recipe, we can do that with `abra recipe sync wordpress`. You'll be prompted by a question asking what kind of upgrade this is. Take a moment to read the output and if it still doesn't make sense, read [this](/maintainers/handbook/#how-are-recipes-are-versioned). Since we're upgrading from `5.8.3` -> `5.9.0`, it is a minor release, so we choose `minor`:
 
@@ -374,7 +374,7 @@ And once more, we can validate this tag has been created with `cd ~/.abra/recipe
 
 ## How are new recipe versions tested?
 
-This is currently a manual process. Our best estimates are to do a backup and run a test deployment and see how things go.
+This is currently a manual process. Our best estimates are to do a backup and run a test deployment and see how things go. [We are working on improving this](https://git.coopcloud.tech/toolshed/-/projects/31).
 
 Following the [entry above](/maintainers/handbook/#how-do-i-release-a-new-recipe-version), before running `abra recipe release --publish <recipe>`, you can deploy the new version of the recipe. You find an app that relies on this recipe and pass `-C/--chaos` to `ugrade` so that it accepts the locally unstaged changes.
 
@@ -391,12 +391,16 @@ If you don't have time or are not an operator, reach out on our communication ch
 In the root of your recipe repository, run the following (if the folder doesn't already exist):
 
 ```
-mkdir -p releases
+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 "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the > 0.9.x series of `abra`.
 
 ## How do I generate the recipe catalogue
 
@@ -427,7 +431,7 @@ You can pass `--publish` to have `abra` automatically publish those changes.
 
     In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
 
-## How is I make the catalogue automatically regenerate after new versions are published? 
+## How do I make the catalogue automatically regenerate after new versions are published? 
 
 "I'd like to make it so that whenever I push a new git tag to the
 [`coop-cloud/rallly` repository](https://git.coopcloud.tech/coop-cloud/rallly)
@@ -453,13 +457,21 @@ release`](#how-do-i-release-a-new-recipe-version)), it automatically does the
 
 ## How does automatic catalogue regeneration work?
 
-TODO
+**TODO: write up properly**
+
+Context: the catalogue lives in a git repo here: https://git.coopcloud.tech/toolshed/recipes-catalogue-json
+
+The expectation is that this repo will only be updated automatically. While manual commits are possible, they're likely to be overwritten.
+
+Automatic regeneration is handled by this Drone step, in the separate `auto-recipes-catalogue-json` repo: https://git.coopcloud.tech/toolshed/auto-recipes-catalogue-json/src/branch/main/.drone.yml#L5-L25
+
+This is run on a daily schedule (question: where is `nightly-app-date` configured?), and can also be triggered by recipe repositories to make new versions available quicker – see "[How do I make the catalogue automatically regenerate after new versions are published?](#how-do-i-make-the-catalogue-automatically-regenerate-after-new-versions-are-published)" above.
 
 ## How do I enable healthchecks
 
 A healthcheck is an important and often overlooked part of the recipe configuration. It is part of the configuration that the runtime uses to figure out if a container is really up-and-running. You can tweak what command to run, how often and how many times to try until you assume the container is not up.
 
-There are no real univesal configs and most maintainers just pick up what others are doing and try to adapt. There is some testing involved to see what works well. You can browse the existing recipe repositories and see from there.
+There are no real universal configs and most maintainers just pick up what others are doing and try to adapt. There is some testing involved to see what works well. You can browse the existing recipe repositories and see from there.
 
 You'll often find the same one used for things like caches & supporting services, such as Redis:
 
@@ -529,6 +541,32 @@ word" style generator but instead a string of characters to match the exact
 length. This can be useful if you have to generate "key" style values instead
 of passwords which admins have to type out in database shells.
 
+## How do I change secret generation characters?
+
+It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
+
+You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
+
+Here are some examples:
+
+```bash
+SECRET_ADMIN_INIT_PASSWORD_VERSION=v1 # length=64 charset=default,safespecial
+SECRET_SERVICE_PASSWORD_VERSION=v1 # length=64 charset=default,special
+```
+
+The possible Values are:
+
+|                    Value                     |                               Characters                                |                                        Description                                        |
+| -------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `special`                                    | `!@#$%^&*_-+=`                                                          | Uses only Special Characters                                                              |
+| `safespecial`                                | `!@#%^&*_-+=`                                                           | Uses only Special Characters, but removes the dollar sign for Console safety              |
+| `default,special`                            | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and special characters              |
+| `default,safespecial`                        | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#%^&*_-+=`  | Uses uppercase letters, lowercase letters and numbers and console safe special characters |
+| `default`                                    | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789`             | Uses uppercase letters, lowercase letters and numbers                                     |
+| any other value or not setting one will be treated as `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789`             | Uses uppercase letters, lowercase letters and numbers                                     |
+
+The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length.
+
 ## How are recipes added to the catalogue?
 
 > This is so far a manual process which requires someone who's been added to the
@@ -551,7 +589,7 @@ visibility for other co-op hosters & end-users.
 
 For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/) if you want to add your recipe to the catalogue.
 
-In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/coop-cloud/organising/issues/139).
+In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).
 
 ## How do I configure backup/restore?
 
@@ -563,7 +601,7 @@ backup/restore logic.
 
 Two of the current "blessed" options are
 [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) &
-[`abra`](https://git.coopcloud.tech/coop-cloud/abra).
+[`abra`](https://git.coopcloud.tech/toolshed/abra).
 
 #### `backup-bot-two`
 
@@ -678,6 +716,11 @@ Please note:
 1. The `file_env` / `_FILE` hack is to pass secrets into the container runtime without exposing them in plaintext in the configuration. See [this entry](/maintainers/handbook/#exposing-secrets) for more.
 
 1. In order to pass execution back to the original entrypoint, it's a good idea to find the original entrypoint script and run it from your own entrypoint script. If there is none, you may want to reference the `CMD` definition or if that isn't working, try to actually specify `cmd: ...` in the `compose.yml` definition (there are other recipes which do this).
+  
+1. Also it might be necessary to define command: although there is an original entrypoint. That's [due to the fact](https://docs.docker.com/reference/compose-file/services/#entrypoint) that if entrypoint is non-null, Compose ignores any default command from the image, for example the `CMD` instruction in the Dockerfile.
+
+  1. Pratically you would e.g. look for the Dockerfile of the upstream image. In there you should find the docker-entrypoint.sh (or similar) and where it's located. Furthermore you find the `CMD`-line there. 
+  1. Just put in your entrypoint.sh in the last line: exec /path/to/docker-entrypoint.sh "@" (path and filename you should find in upstream Dockerfile) and insert  command:  to your service in compose.yml with the value of what you find in the CMD line of the Dockerfile.
 
 1. If you're feeling reckless, you can also use the Golang templating engine to do things conditionally.
 
@@ -692,6 +735,21 @@ You should be able to deploy this overriden configuration now.
 
 ## Linting rules
 
+### R015: "long secret names"
+
+Due to limitations placed by the Docker runtime, secret names must be < 64
+characters long. Due to convetions in recipe configuration and how `abra`
+works, several characters are appended to secret names during a deployment.
+This means if you have a domain `example.org` and a secret `foo_pass`, you'll
+end up with something like `example_org_foo_pass_v1` being used for the secret
+name.
+
+Based on a discussion in
+[`#463`](https://git.coopcloud.tech/toolshed/organising/issues/463) and
+looking on what is implemented currently in existing recipes, we came up with a
+general rule of thumb that secret names in recipe configurations should be < 12
+characters long to avoid errors on deployment.
+
 ### R014: "invalid lightweight tag"
 
 This is an issue related to the way Git/`go-git` handle Git tags internally. We

docs/maintainers/tutorial.md

@@ -10,7 +10,7 @@ Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn
 
 The nice thing about packaging is that only one person has to do it and then we all benefit. We've seen that over time, the core of the configuration doesn't really change. New options and versions might come but the config remains quite stable. This is good since it means that your packaging work stays relevant and useful for other maintainers & operators as time goes on.
 
-Depending on your familiarity with recipes, it might be worth reading [how a recipe is structured](/maintainers/handbook/#how-is-a-recipe-structured) and making clear you understand [what a recipe is](/glossary/#recipe) before continuing.
+Depending on your familiarity with recipes, it might be worth reading [how a recipe is structured](/maintainers/handbook/#how-is-a-recipe-structured) and making clear you understand [what a recipe is](/intro/glossary/#recipe) before continuing.
 
 ### Making a plan
 
@@ -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/operators/handbook.md

@@ -205,18 +205,6 @@ At time of writing (Jan 2022), we think there is a limitation in our design whic
 
 This may be possible to overcome if someone really needs it, we encourage people to investigate. We've found that often there are limitations in the actual software which don't support this anyway and several of the current operators simply use a new domain per app.
 
-## Creating a new server
-
-`abra server new` can create servers if you have an account with a supported 3rd party integration. We currently support [Servers.coop](https://servers.coop) & [Hetzner](https://hetzner.com). The process of creating a new server usually goes like this:
-
-1. Create an account with a server hosting provider
-2. Generate an API client key which you'll give to `abra`
-3. Run `abra server new` & fill in the values
-
-`abra` supports creating, listing and removing servers if the 3rd party integration supports it.
-
-If you want to teach `abra` how to support your favourite server hosting provider, we'd glady accept patches.
-
 ## How do I bootstrap a server for running Co-op Cloud apps?
 
 The requirements are:
@@ -226,6 +214,12 @@ The requirements are:
 1. Swarm mode initialised
 1. Proxy network created
 
+!!! warning "You may need to log in/out"
+
+    When running `usermod ...`, you may need to (depending on your system) log
+    in and out again of your shell session to get the required permissions for
+    Docker.
+
 ```
 # docker install convenience script
 wget -O- https://get.docker.com | bash
@@ -242,18 +236,6 @@ apt install apparmor
 systemctl restart docker containerd
 ```
 
-## Managing DNS entries
-
-`abra record ...` can help you manage your DNS entries if you have an account with a supported 3rd party provider. We currently support [Gandi](https://gandi.net). The process of managing DNS with `abra` usually goes like this:
-
-1. Create an account with a DNS service provider
-2. Generate an API client key which you'll give to `abra`
-3. Run `abra record ls` to check everything works
-
-`abra` supports creating, listing and removing DNS entries if the 3rd party integration supports it.
-
-If you want to teach `abra` how to support your favourite DNS service provider, we'd glady accept patches.
-
 ## How do I persist container logs after they go away?
 
 This is a big topic but in general, if you're looking for something quick & easy, you can use the [journald logging driver](https://docs.docker.com/config/containers/logging/journald/). This will hook the container logs into systemd which can handle persistent log collection & managing log file size.
@@ -329,27 +311,40 @@ If you need to run a command on a container that won't start (eg. the container
 > ... there was really nothing to it, apart from making sure to use multiarch
 > or arm images
 
-See [`#312`](https://git.coopcloud.tech/coop-cloud/organising/issues/312) for more.
+See [`#312`](https://git.coopcloud.tech/toolshed/organising/issues/312) for more.
 
 ## How do I backup/restore my app?
 
-If you're app [supports backup/restore](/maintainers/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/coop-cloud/abra).
+If you're app [supports backup/restore](/maintainers/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/toolshed/abra).
+
+With `abra`, you can simply run the commands:
+
+```
+$ abra app backup <domain>
+$ abra app restore <domain>
+```
 
-With `abra`, you can simply run `abra app backup ...` & `abra app restore ...`.
 Pass `-h` for more information on the specific flags & arguments.
 
+If your app Recipe *does not support backups* you can do it manually with the
+`abra cp` command. See the exact commands in [abra
+cheetsheet](/abra/cheat-sheet/#manually-restoring-app-data).
+
+
 ## How do I take a manual database backup?
 
 MySQL / MariaDB:
 
 ```
-abra app run foo.bar.com db mysqldump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
+abra app run foo.bar.com db mysqldump -u root <database> \
+  | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
 ```
 
 Postgres:
 
 ```
-abra app run foo.bar.com db pg_dump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
+abra app run foo.bar.com db pg_dump -u root <database> | \
+  gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
 ```
 
 If you get errors about database access:
@@ -358,7 +353,8 @@ If you get errors about database access:
     something like this:
 
 ```
-abra app run foo.bar.com db bash -c 'mysqldump -u root -p"$(cat /run/secrets/db_oot_password)" <database>' | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
+abra app run foo.bar.com db \
+  bash -c 'mysqldump -u root -p"$(cat /run/secrets/db_oot_password)" <database>' | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
 ```
 
 ## Can I deploy a recipe without `abra`?
@@ -462,3 +458,144 @@ route requests after. You're free to make as many `$whatever.yml` files in your
 
  Please note that we have to hardcode `production` and `web-secure` which are
  typically configurable when not using `FILE_PROVIDER_DIRECTORY_ENABLED`.
+
+## Can I use Caddy instead of Traefik?
+
+Yes, it's possible although currently Quite Experimental! See
+[`#388`](https://git.coopcloud.tech/toolshed/organising/issues/388) for more.
+
+## Running an offline coop-cloud server 
+
+You may want to run a coop-cloud directly on your device (or in a VM or machine on your LAN), whether that's for testing a recipe or to run coop-cloud apps outside of the cloud ;-)
+In that case you might simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
+1. In your traefik .env file, edit/uncomment the following lines:
+```
+LETS_ENCRYPT_ENV=staging
+WILDCARDS_ENABLED=1
+SECRET_WILDCARD_CERT_VERSION=v1
+SECRET_WILDCARD_KEY_VERSION=v1
+COMPOSE_FILE="$COMPOSE_FILE:compose.wildcard.yml"
+```
+2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`
+3. Run these commands:
+```
+abra app secret insert localhost ssl_cert v1 localhost.crt -f
+abra app secret insert localhost ssl_key v1 localhost.key -f
+```
+4. Re-deploy `traefik` with `--force` and voila!
+
+## Remote recipes
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the > 0.10.x series of `abra`.
+
+It is possible to specify a remote recipe in your `.env` file:
+
+```
+RECIPE=mygit.org/myorg/cool-recipe.git:1.3.12
+```
+
+Where `1.3.12` is an optional pinned version. When `abra` runs a deployment, it
+will fetch the remote recipe and create a directory for it under `$ABRA_DIR`
+(typically `~/.abra`):
+
+```
+$ABRA_DIR/recipes/mygit_org_myorg_cool-recipe
+```
+
+## Saving the version to the app `.env` file
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the > 0.10.x series of `abra`.
+
+If you `abra app new`/`abra app deploy`/`abra app upgrade`/`abra app rollback`,
+the version that is deployed will be written to your app `.env` file. You can
+see this in the `TYPE=/RECIPE=` line of the `.env` where the recipe name is
+shown.
+
+For example, before a deployment of the `custom-html` recipe:
+
+```
+TYPE=custom-html
+```
+
+And after a deployment of version `1.7.1+1.27.2` of the `custom-html` recipe.
+
+```
+TYPE=custom-html:1.7.1+1.27.2
+```
+
+This `.env` version is then used as the recipe checkout version for **all**
+`abra` operations afterwards unless you specify otherwise on the command-line
+with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
+
+## How is the new deployment version determined?
+
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the > 0.10.x series of `abra`.
+
+### `.env` version
+
+If you `abra app deploy`/`abra app upgrade`/`abra app rollback`, the version
+that is deployed will be written to your app `.env` file. This is shown in the
+deployment overview.
+
+This `.env` version is then used as the recipe checkout version for **all**
+`abra` operations afterwards unless you specify otherwise on the command-line
+with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
+
+### `abra app deploy`
+
+This is the most flexible command so it can be hard to follow. It is possible
+to deploy the following kinds of versions with `abra app deploy`:
+
+1. latest recipe version if no `.env` version (standard `abra app deploy`)
+1. version retrieved from the app `.env` (`abra app deploy` + `TYPE=custom-html:1.7.1+1.27.2`)
+1. latest commit (`--chaos/-C` / `abra app deploy` + no released recipe versions)
+1. latest commit with unstaged changes (`abra app deploy --chaos/-C`)
+1. recipe version or Git hash (`abra app deploy 1.7.1+1.27.2`)
+
+The app `.env` version is always used as the recipe checkout version if
+present.
+
+The version is chosen using the following priority logic.
+
+1. cli argument
+1. `.env` file
+1. deployed app
+1. recipe catalogue (if undeployed)
+
+Use `--ignore-env-version/-i` to deploy the latest release version or commit.
+
+In all cases 3-5, the app `.env` version is **ignored** as a version candidate.
+
+### `abra app upgrade`
+
+The app must be deployed already to proceed.
+
+* a new upgrade (standard `abra app upgrade`)
+* a specific upgrade (`abra app upgrade 1.7.1+1.27.2`)
+* force re-upgrade (same version, `abra app upgrade --force`)
+
+The app `.env` version is always used as the recipe checkout version if
+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.
+
+### `abra app rollback`
+
+The app must be deployed already to proceed.
+
+* a new downgrade (standard `abra app rollback`)
+* a specific downgrade (`abra app rollback 1.7.1+1.27.2`)
+* force re-downgrade (same version, `abra app rollback --force`)
+
+The app `.env` version is always used as the recipe checkout version if
+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.

docs/operators/tutorial.md

@@ -13,13 +13,6 @@ In order to deploy an app you need two things:
 
 This tutorial tries to help you make choices about which server and which DNS setup you need to run a _Co-op Cloud_ deployment but it does not go into great depth about how to set up a new server.
 
-??? question "Can `abra` help automate this?"
-
-    Our `abra` tool can help bootstrap new servers & configure DNS records for
-    you. We'll skip that for now since we're just getting started. For more on
-    these topics after you finish the tutorial see the [operators
-    handbook](/operators/handbook).
-
 ### Server setup
 
 Co-op Cloud has itself near zero system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
@@ -32,17 +25,44 @@ You need to keep port `:80` and `:443` free on your server for web proxying to y
 
 `abra` has support for creating servers (`abra server new`) but that is a more advanced automation feature which is covered in the [handbook](/operators/handbook). For this tutorial, we'll focus on the basics. Assuming you've managed to create a testing VPS with some `$hosting_provider`, you'll need to install Docker, add your user to the Docker group & setup swarm mode:
 
+!!! warning "You may need to log in/out"
+
+    When running `usermod ...`, you may need to (depending on your system) log
+    in and out again of your shell session to get the required permissions for
+    Docker.
+    Alternatively you can run [`newgrp`](https://www.man7.org/linux/man-pages/man1/newgrp.1.html) to register the group chnage.
+
 ```
+# ssh into your server
+ssh <server-domain>
+
 # docker install convenience script
 wget -O- https://get.docker.com | bash
 
+# check if the docker group exists
+groups | grep docker
+
+# if the docker group doesn't already exist, add it manually
+sudo groupadd docker
+
 # add user to docker group
 sudo usermod -aG docker $USER
 
-# setup swarm
+# check that docker installed correctly
+docker run hello-world
+
+# exit and re-login to load the group
+exit
+ssh <server-domain>
+
+# back on the server, setup swarm
 docker swarm init
 docker network create -d overlay proxy
+
+# now you can exit and start using abra
+exit
 ```
+Abra can't deploy any applications in future steps if the docker group cannot run without sudo. If you install docker a different way, it may not create a docker group automatically. The [official Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/) can help if you run into further issues.
 
 ??? question "Do you support multiple web proxies?"
 
@@ -59,6 +79,8 @@ Your entries in your DNS provider setup might look like the following.
 
 Where `116.203.211.204` can be replaced with the IP address of your server.
 
+Warning: If the you are in the same local netwrok as the server, you might run into [NAT Hairpin](https://superuser.com/questions/663820/port-forwarding-from-inner-network-to-inner-network-hairpin-nat) issues.
+
 ??? question "How do I know my DNS is working?"
 
     You can use a tool like `dig` on the command-line to check if your server has the necessary DNS records set up. Something like `dig +short <domain>` should show the IP address of your server if things are working.
@@ -66,7 +88,7 @@ Where `116.203.211.204` can be replaced with the IP address of your server.
 ### Install `abra`
 
 Now we can install [`abra`](/abra) locally on your machine and hook it up to
-your server. We support a script-based installation method ([script source](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer)):
+your server. We support a script-based installation method ([script source](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer/installer)):
 
 ```bash
 curl https://install.abra.coopcloud.tech | bash
@@ -79,32 +101,63 @@ that everything is working try listing the `--help` command or `-h` to view
 output:
 
 ```bash
-abra -h 
+abra -h
 ```
 
 You may need to add the `~/.local/bin/` directory to your `$PATH` variable, in
-order to run the executable.
+order to run the executable. Also, run this line into your terminal so
+you have immediate access to `abra` on the current terminal.
 
 ```bash
 export PATH=$PATH:$HOME/.local/bin
 ```
 
-If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/coop-cloud/organising/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this.
+If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/toolshed/organising/issues/new) :pray:
 
 ??? question "Can I install `abra` on my server?"
 
     Yes, this is possible. However, the instructions for this setup are different. For more info see [this handbook entry](/operators/handbook/#running-abra-server-side).
 
+### Set up autocomplete
+
+Most `abra` commands require typing the fully qualified domain name for your app, so we **highly** recommend configuring command-line auto-completion. See `abra autocomplete -h` for more on how to do this. The instructions vary depending on which shell you use.
+
+With autocomplete enabled, you can run a command like `abra app deploy myapp.example.com` by just typing `abra app deploy myapp<tab>`.
+
 ### Add your server
 
-Now you can connect `abra` with your server. You should have a working SSH configuration before you can do this (e.g. a matching `Host <server-domain>` entry in `~/.ssh/config` with the correct SSH connection details). That means you can run `ssh <server-domain>` on your command-line and everything Works :tm:.
+Now you can connect `abra` with your server. You must have a working SSH configuration for your server before you can proceed. That means you can run `ssh <server-domain>` on your command-line and everything Works :tm:. See the [`abra` SSH troubleshooting](/abra/trouble/#ssh-connection-issues) for a working SSH configuration example.
+
+??? warning "Beware of SSH dragons :dragon_face:"
+
+    Under the hood `abra` uses plain 'ol `ssh` and aims to make use of your
+    existing SSH configurations in `~/.ssh/config` and interfaces with your
+    running `ssh-agent` for password protected secret key files.
+
+    Running `server add` with `-d` or `--debug` should help you debug what is
+    going on under the hood. `ssh -v ...` should also help. If you're running
+    into SSH connection issues with `abra` take a moment to read [this
+    troubleshooting entry](/abra/trouble/#ssh-connection-issues).
 
 ```bash
 ssh <server-domain> # make sure it works
 abra server add <server-domain>
 ```
 
-It is important to note that `<domain>` here is a publicy accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting.
+It is important to note that `<server-domain>` here is a publicy accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting.
+
+??? warning "Can I use arbitrary server names?"
+
+    Yes, this is possible. You need to pass `-D` to `server add` and ensure
+    that your `Host ...` entry in your SSH configuration includes the name.
+    So, for example, in `~/.ssh/config`:
+    ```
+      Host example.com example
+        ...
+    ```
+    And then:
+
+      abra server add example
 
 You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance.
 
@@ -114,49 +167,65 @@ By now `abra` should have registered this server as managed. To confirm this run
 abra server ls
 ```
 
-??? warning "Beware of SSH dragons :dragon_face:"
-
-    Under the hood `abra` uses plain 'ol `ssh` and aims to make use of your
-    existing SSH configurations in `~/.ssh/config` and interfaces with your
-    running `ssh-agent` for password protected secret key files.
-
-    Running `server add` with `-d` or `--debug` should help you debug what is going
-    on under the hood. If you're running into SSH connection issues with `abra`
-    take a moment to read [this troubleshooting
-    entry](/abra/trouble/#ssh-connection-issues).
-
 ??? question "How do I share my configs in `~/.abra`?"
 
-    It's possible and quite easy, for more see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration).
+    It's possible and quite easy, for more see [this handbook
+    entry](/operators/handbook/#understanding-app-and-server-configuration).
 
 ### Web proxy setup
 
 In order to have your Co-op cloud deployment serve the public internet, we need to install the core web proxy, [Traefik](https://doc.traefik.io/traefik/).
 
-Traefik is the main entrypoint for all web requests (e.g. like NGINX) and supports automatic SSL certificate configuration and other quality-of-life features which make deploying libre apps more enjoyable.
+Traefik is the main entrypoint for all web requests (e.g. like NGINX) and
+supports automatic SSL certificate configuration and other quality-of-life
+features which make deploying libre apps more enjoyable.
 
-To get started, you'll need to create a new app:
+**1. To get started, you'll need to create a new app:**
 
 ```bash
 abra app new traefik
 ```
 
-Choose your newly registered server and specify a domain name.
+Choose your newly registered server and specify a domain name. By default `abra`
+will suggest `<app-name>.server.org` or prompt you with a list of servers.
 
-You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value. You can do that by running `abra app config`:
+
+**2. Configure this new `traefix` app**
+
+You will want to take a look at your generated configuration and update the placeholder `LETS_ENCRYPT_EMAIL` value, used by Let's Encrypt to manage SSL certificates. You can do that by running `abra app config`:
 
 ```bash
 abra app config <traefik-domain>
 ```
 
-Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required.
+Every app you deploy will have one of these `.env` files, which contains
+variables which will be injected into app configurations when deployed. These
+files exist at relevantly named path:
 
-Now it is time to deploy:
+```bash
+~/.abra/servers/<domain>/<traefik-domain>.env
+```
+
+Variables starting with `#` are optional, others are required. Some things to
+consider here is that by default our *Traefik* recipe exposes the metric
+dashboard unauthenticated on the public internet at the URL `<traefik-domain>`
+it is deployed to, which while helpful for debugging, is not ideal in production environments. You can disable this with:
+
+```
+DASHBOARD_ENABLED=false
+```
+
+**3. Now it is time to deploy your app:**
+
+Ensure `<traefic-domain>` is registered in `/etc/hosts` then run:
 
 ```
 abra app deploy <traefik-domain>
 ```
 
+Voila. Abracadabra :magic_wand: your first app is deployed :sparkles:
+
+
 ### Deploy Nextcloud
 
 And now we can deploy apps. Let's create a new Nextcloud app.
@@ -171,7 +240,7 @@ The `-S` or `--secrets` flag is used to generate secrets for the app: database c
 
     Take care, these secrets are only shown once on the terminal so make sure to take note of them! `abra` makes use of the [Docker secrets](/operators/handbook/#managing-secret-data) mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in `/run/secrets` on the container file system.
 
-Then we can deploy Nextcloud:
+Make sure` <nextcloud-domain>` is registered in `/etc/hosts`, then we can deploy Nextcloud:
 
 ```bash
 abra app deploy <nextcloud-domain>
@@ -228,4 +297,4 @@ Add `ENABLE_AUTO_UPDATE=true` to the env config (`abra app config <app name>`) t
 
 Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.
 
-If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.
+If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/toolshed/organising/issues/new/choose) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.

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](/specs/backup/spec/).
+
+- [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)
+- [`abra`](https://git.coopcloud.tech/toolshed/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,12 +1,13 @@
 ---
 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
 
 theme:
   name: material
   features:
+      navigation.instant.progress
     - content.action.edit
     - navigation.expand
     - navigation.indexes
@@ -15,6 +16,7 @@ theme:
     - navigation.sections
     - navigation.tabs
     - navigation.tabs.sticky
+    - navigation.top
     - navigation.tracking
   palette:
     primary: light pink
@@ -23,7 +25,7 @@ theme:
   favicon: img/favicon.ico
   custom_dir: custom_theme/
 
-copyright: Copyleft 2023 Co-op Cloud
+copyright: Copyleft 2020-2025 Co-op Cloud
 
 markdown_extensions:
   - admonition
@@ -61,87 +63,114 @@ nav:
       - "Frequently Asked Questions": intro/faq.md
       - "Project Strategy": intro/strategy.md
       - "Comparisons": intro/comparisons.md
+      - "Inspirations": intro/inspirations.md
       - "Project Status": intro/bikemap.md
       - "Managed Hosting": intro/managed.md
       - "Get In Touch": intro/contact.md
       - "Credits": intro/credits.md
-  - "Operators":
-      - operators/index.md
-      - "New Operators Tutorial": operators/tutorial.md
-      - "Operations Handbook": operators/handbook.md
+      - intro/get-involved.md
+      - intro/glossary.md
+      - "Support Us": intro/support.md
   - "Maintainers":
       - maintainers/index.md
       - "New Maintainers Tutorial": maintainers/tutorial.md
       - "Packaging Handbook": maintainers/handbook.md
-  - "Organisers":
-      - 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
+  - "Operators":
+      - operators/index.md
+      - "New operators Tutorial": operators/tutorial.md
+      - "Operators Handbook": operators/handbook.md      
+  - "Federation":
+      - federation/index.md
+      - federation/handbook.md
+      - federation/organisers.md
+      - "Bylaws": federation/bylaws.md
+      - "Finance": federation/finance.md
+      - "Membership": federation/membership.md
+      - "Code of Co-operation": federation/code-of-coop.md
       - "Proposals":
-        - organisers/proposals/index.md
-        - organisers/proposals/federation.md
+        - federation/proposals/index.md
+        - federation/proposals/federation.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
+              - federation/resolutions/passed/021.md
+              - federation/resolutions/passed/022.md
+              - federation/resolutions/passed/023.md
+              - federation/resolutions/passed/024.md
+              - federation/resolutions/passed/025.md
+              - federation/resolutions/passed/026.md
+              - federation/resolutions/passed/027.md
+              - federation/resolutions/passed/028.md
+              - federation/resolutions/passed/029.md
+          - "Stalled":
+              - federation/resolutions/stalled/013.md
+          - "In Progress":
+              - federation/resolutions/index.md
+              - federation/resolutions/in-progress/030-docs-naming-survey.md
+              - federation/resolutions/in-progress/031.md
+      - "Minutes":
+          - federation/minutes/index.md
+          - "Recently":
+              - federation/minutes/2024-08-15.md
+              - federation/minutes/2024-04-17.md
+              - federation/minutes/2024-03-29.md
+          - "Archive":
+              - federation/minutes/2024-02-01.md
+              - federation/minutes/2022-03-03.md
+              - federation/minutes/2023-05-03.md
+      - "Digital Tools": federation/tools.md
+      - "Funding applications":
+          - federation/funding-applications/index.md
+          - federation/funding-applications/culture-of-solidarity.md
+          - federation/funding-applications/ford-foundation.md
+          - federation/funding-applications/private-funder.md
+          - federation/funding-applications/sovereign-tech-fund.md
+          - federation/funding-applications/user-operated-internet.md
   - "Abra":
       - abra/index.md
       - "Install": abra/install.md
       - "Quick Start": abra/quickstart.md
       - "Upgrade": abra/upgrade.md
+      - "Design": abra/design.md
       - "Recipes": abra/recipes.md
       - "Hack": abra/hack.md
       - "Troubleshoot": abra/trouble.md
       - "Cheat Sheet": abra/cheat-sheet.md
-  - "Get Involved":
-      - get-involved/index.md
-      - "Support Us": get-involved/support.md
-  - "Federation":
-      - federation/index.md
-      - "Bylaws": federation/bylaws.md
-      - "Finance": federation/finance.md
-      - "Membership": federation/membership.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
-        - "In Progress":
-          - federation/resolutions/in-progress/013.md
-          - federation/resolutions/in-progress/018.md
-      - "Minutes":
-        - federation/minutes/index.md
-        - "Recently":
-          - federation/minutes/2024-02-01.md
-        - "Archive":
-          - federation/minutes/2022-03-03.md
-          - federation/minutes/2023-05-03.md
-      - "Digital Tools": federation/tools.md
-  - "Glossary":
-    - glossary/index.md
+  - "Specifications":
+      - specs/index.md
+      - "Backups":
+          - specs/backup/index.md
+          - specs/backup/maintain.md
+          - specs/backup/spec.md
 
 plugins:
   - awesome-pages
   - search
+  - redirects:
+      redirect_maps:
+        "get-involved/support/index.md": intro/support.md
 
-repo_name: coop-cloud/docs.coopcloud.tech
-repo_url: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/
+repo_name: toolshed/docs.coopcloud.tech
+repo_url: https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/
 edit_uri: _edit/main/docs/
 
 extra_css:

requirements.txt

@@ -1,15 +1,15 @@
-markdown~=3.2
+mkdocs~=1.6.1
 
-mkdocs~=1.5.3
-mkdocs-material~=9.5.7
-mkdocs-material-extensions~=1.3.1
-mkdocs-awesome-pages-plugin==2.9.2
-pygments~=2.16
-pymdown-extensions~=10.2
+mkdocs-material==9.5.49
+mkdocs-material-extensions==1.3.1
+mkdocs-awesome-pages-plugin==2.10.1
+pygments==2.19.1
+pymdown-extensions==10.14
+mkdocs-redirects==1.2.2
 
 # Requirements for plugins
-babel~=2.10
-colorama~=0.4
-paginate~=0.5
+babel==2.16.0
+colorama==0.4.6
+paginate==0.5.7
 regex>=2022.4
-requests~=2.26
+requests==2.32.3