updated info on local-it and (new) makeITsocial

2025-01-13 15:15:04 +00:00
56 changed files with 206 additions and 838 deletions
@@ -12,8 +12,8 @@ In other words, we're happy to give you, as contributor, "the commit bit" (read/

 We maintain a "team" called "Co-operators" on our 2 main repositories:

-* [`git.coopcloud.tech/org/toolshed`](https://git.coopcloud.tech/toolshed/)
-* [`git.coopcloud.tech/org/coop-cloud`](https://git.coopcloud.tech/coop-cloud/)
+* [`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.

@@ -38,21 +38,6 @@ Our [Drone CI configuration](https://git.coopcloud.tech/toolshed/abra/src/branch

 Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.

-### Super quick-start (Ubuntu Server)
-
-```bash
-cd 
-sudo apt update && DEBIAN_FRONTEND=noninteractive sudo apt install -y golang make git 
-git clone https://git.coopcloud.tech/toolshed/abra.git && cd abra 
-make build
-mkdir -p  ~/.local/bin/
-ln -sF $PWD/abra ~/.local/bin/abradev
-if [[ "$PATH" != *".local/bin"* ]]; then export PATH="$PATH:~/.local/bin/"; echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc; fi
-# Set up Spanish auto-completion
-LANG=es abra autocompletar bash | sed 's/abra/abradev/g' | sudo tee /etc/bash_completion.d/abra-dev
-abradev --help
-```
-
 ## Unit tests

 ### Run tests
@@ -106,26 +91,6 @@ Please ask `@decentral1se` or on the Matrix channels for SSH access to the machi

 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).

-##### Fedora 
-
-```
-sudo dnf install bats
-```
-
-Unfortunately, the Fedora `bats` package doesn't include the libraries we need, so we need to clone those manually:
-
-```
-mkdir -p ~/.local/share/bats/
-cd ~/.local/share/bats
-git clone https://github.com/bats-core/bats-assert.git
-git clone https://github.com/bats-core/bats-file.git
-git clone https://github.com/bats-core/bats-support.git
-```
-
-Then, before running tests, set `export BATS_LIB_PATH=~/.local/share/bats/`
-
-##### Debian
-
 ```
 apt install bats-file bats-assert bats-support jq make git
 ```
@@ -146,7 +111,7 @@ For some tests an actual server is needed, where apps can be deployed. You can e
 ##### Remote swarm

 ```
-export TEST_SERVER="test.example.com"
+export ABRA_TEST_DOMAIN="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
 ```

@@ -235,62 +200,6 @@ bats -Tp tests/integration --filter-status failed # re-run only failed

 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.

-## Internationalisation (`i18n`)
-
-`abra` can be translated into other languages. We use a combination of [`gettext`](https://www.gnu.org/software/gettext/), [`weblate`](https://translate.coopcloud.tech) and some [intermediate automation](https://git.coopcloud.tech/toolshed/abra/src/commit/20909695e0e05c6251029dba270b3d4741aeb7a8/.drone.yml#L10-L29) to help developers and translators work together conveniently.
-
-### Developer workflow
-
-You just hack on `abra` as you normally would.
-
-If you need to add a string, use `i18n.G` to wrap it. See [`gotext`](https://github.com/leonelquinteros/gotext) for the full API.
-
-For example.
-
-```go
-i18n.G("my string")
-i18n.G("my string with err: %s", err)
-log.Debug(i18n.G("my string"))
-log.Info(i18n.G("my string with err: %s", err))  # N.B no log.Infof usage here
-```
-
-Then you need to update the `pkg/i18n/locales/abra.pot` file with your new strings for the translators.
-
-```bash
-apt install -y gettext
-go install -v -x github.com/snapcore/snapd/i18n/xgettext-go@2.57.1
-make i18n
-```
-
-Commit the changes. Ignore `*.mo` changes if they only update the generation timestamp.
-
-#### Resolving a merge conflict
-
-```
-git remote add weblate https://translate.coopcloud.tech/git/co-op-cloud/abra/
-git remote update weblate
-git merge weblate/main
-```
-
-Once you've resolved the conflict and pushed it, you'll need admin permissions on the Weblate repository to unlock it.
-
-### Translator workflow
-
-You can translate strings on [Weblate (`translate.coopcloud.tech`)](https://translate.coopcloud.tech). 
-
-It's also possible to translate using [`poedit`](https://poedit.net). Weblate is the recommended approach. 
-
-All translation files are located in [`pkg/i18n/locales`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/i18n/locales). Once translations are updated in weblate, they will be incorporated into the next release of `abra` automatically.
-
-### End-user workflow
-
-You simply export the `LANG` env var to match your desired translation.
-
-```
-export LANG=es
-abra -h
-```
-
 ## Using the `abra` public API

 Warning, there is currently no stability promise for the `abra` public API! Most of the internals are exposed in order to allow a free hand for developers to try build stuff. If people start to build things then we can start the discussion on what is useful to have open/closed and keep stable etc. Please let us know if you depend on the APIs!
@@ -370,26 +279,6 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 - 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`)
- Share the announcement:
-
-```
-📢📢📢 abra v0.XX  is finally here 📢📢📢
-
-TLDR; `abra upgrade` 👍
-
-Upgrade docs:
-https://docs.coopcloud.tech/abra/upgrade/
-
-Changelog:
-https://git.coopcloud.tech/toolshed/abra/releases/tag/0.XX.0-beta
-
-0.XX.x-beta 👉 0.XX.x-beta migration guide:
-https://docs.coopcloud.tech/abra/upgrade/#XXx-beta-0XXx-beta
-
-A huge thanks to everyone who helped get this release done ❤️‍🔥
-
-Happy Hacking 🫂
-```

 ## Fork maintenance

@@ -10,9 +10,7 @@ title: 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:

-`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.
+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)).

 - [Install](/abra/install): You want to install `abra` :100:
 - [Quick start](/abra/quickstart): You're ready to get started using `abra` :muscle:
@@ -4,7 +4,7 @@ title: Troubleshoot

 ## Where do I report `abra` bugs / feature requests?

-You can use [this issue tracker](https://git.coopcloud.tech/toolshed/abra/issues/new).
+You can use [this issue tracker](https://git.coopcloud.tech/toolshed/organising/issues/new/choose).

 ## SSH connection issues?

@@ -23,7 +23,6 @@ Host example.com
 and your IdentityFile should be added to the authentication agent:

 ```
-eval `ssh-agent`
 ssh-add ~/.ssh/example@somewhere
 ```

@@ -84,25 +83,3 @@ This appears to be an upstream issue for which we can't do much in `abra` to sol
 ## 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
-```
-
-## "only updates to Labels are allowed"
-
-See [Packaging handbook » What does "only updates to Labels are allowed" mean](maintainers/handbook/#what-does-only-updates-to-labels-are-allowed-mean).
@@ -53,23 +53,10 @@ And test things work.

 > General release notes are [here](https://git.coopcloud.tech/toolshed/abra/releases/)

-### `0.10.x-beta` -> `0.11.x-beta`
-
-* Timeouts are no longer used unless specifically set in the app `.env` file,
-  e.g `TIMEOUT=180`. Recipe maintainers should remove defaults so that these
-  are not imposed on operators. See
-  [`#596`](https://git.coopcloud.tech/toolshed/abra/issues/596).
-
-* `--ignore-env-version` has gone away as a global flag. `--latest` is now
-  present on `abra app deploy`. See
-  [`#617`](https://git.coopcloud.tech/toolshed/abra/issues/617).
-
-* We now ensure that `$ABRA_DIR/servers` has stricter permissions (`0600`). See
-  [`#592`](https://git.coopcloud.tech/toolshed/abra/pulls/592) for more. No
-  migration step should be required.
-
 ### `0.9.x-beta` -> `0.10.x-beta`

+> 🎺🎺🎺 Get the [release candidate](https://git.coopcloud.tech/toolshed/abra/releases/tag/0.10.0-rc1-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
@@ -92,10 +79,6 @@ And test things work.
 * 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.
-  **WARNING**: you'll need to REMOVE your pre `v0.10.x` `abra` auto-complete
-  config for the new auto-complete to work. Check your `$SHELL` configuration
-  file (e.g. `.zshrc` for Zsh). See
-  [`#553`](https://git.coopcloud.tech/toolshed/abra/issues/553) for more.

 * Several commands now make use of the `--chaos/-C` commands, such as `abra app
  ps` and `abra app cp`. See `--help` for more.
@@ -130,11 +113,6 @@ And test things work.
  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.

@@ -149,13 +127,6 @@ And test things work.

 * `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.
-
-* `abra secret insert` now supports a `--file/-f` flag to support inserting
-  from file without using Bash-isms. See See
-  [`#555`](https://git.coopcloud.tech/toolshed/abra/issues/555) for more.
-
 ### `0.8.x-beta` -> `0.9.x-beta`

 None at this time.
@@ -60,6 +60,10 @@ Finally, please let us know what your username/email is for your Open Collective

 #### FAQ

+##### Where are the bank details of federation members?
+
+Please see [`Finance.md` in the internal Federation Wiki](https://git.coopcloud.tech/Federation/organising/wiki/Finance)
+
 ##### What transfer type do we use for USD?

 `ACH`. If you see `Abartn`, that is the `ACH routing number`.
@@ -32,6 +32,6 @@ Here is some invitation boilerplate which you can use:
 >
 > 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?view). 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.
+> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/LqotfSJJRj69RcTtWmr7iw). 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.
 >
 > Hope to see you there! ☁️ 🌞 🖥️
@@ -38,12 +38,6 @@ 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 }

- __Shared Infrastructure Inventory__
-
-    Tools we maintain for the federation 🛠
-
-    [Tools We Maintain](/federation/infra){ .md-button .md-button--primary }
-
 - __Code of Co-operation__

    Be excellent to each other 💝
@@ -1,22 +0,0 @@
---
-title: Shared Infrastructure Inventory
---
-
-## Shared repository for fedi maintainers
-
-> [coop-cloud-apps](https://git.coopcloud.tech/toolshed/coop-cloud-apps)
-
-## 2025 State of The Co-op Cloud Infra
-
-| service | server | recipe/app | notes |
-| --- | --- | --- | --- |
-| build.coopcloud.tech | `swarm-0.coopcloud.tech` | drone | should probably be moved to separate VPS |
-| (drone build runner) | `swarm-0.coopcloud.tech` | drone-docker-runner | should probably be moved to separate VPS |
-| git.coopcloud.tech |  `swarm-0.coopcloud.tech` | gitea | |
-| recipes.coopcloud.tech |  `swarm-0.coopcloud.tech` | [toolshed/recipes.coopcloud.tech](https://git.coopcloud.tech/coop-cloud/recipes.coopcloud.tech/)
-| recipes.coopcloud.tech/recipes.json | `swarm-0.coopcloud.tech` | [toolshed/recipes-catalogue-json](https://git.coopcloud.tech/toolshed/recipes-catalogue-json) | |
-| coopcloud.tech | `swarm-0.coopcloud.tech` | [toolshed/coopcloud.tech](https://git.coopcloud.tech/coop-cloud/coopcloud.tech/) | |
-| docs.coopcloud.tech | `swarm-0.coopcloud.tech` | [toolshed/docs.coopcloud.tech](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/) |  |
-| install.abra.coopcloud.tech | `swarm-0.coopcloud.tech` | [toolshed/abra/scripts/installer](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/installer) | |
-| sso.coopcloud.tech | `swarm-1.coopcloud.tech` | rauthy | |
-| translate.coopcloud.tech | `swarm-1.coopcloud.tech` | weblate | |
@@ -16,8 +16,6 @@ title: Membership
 | [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` |
+| [BeWater](https://bewater.contact) | Waiver | - | `@decentral1se` |
 | [ruangrupa](https://ruangrupa.id) | - | - | Henry `@babystepper:matrix.org` |
-| [RTM](https://resisttechmonopolies.online) | ✅ | - | `@ammaratef45:matrix.org` + `@linnealovespie:matrix.org`|
-| [MIR](https://mirnet.org/) | ✅ | - | `@sixsmith:matrix.org` |
-| [Red Abya Yala](https://abyayala.sutty.nl/) | - | - | `@fauno:sutty.nl` |
+| [Ammar](https://social.coop/@ammaratef45) | - | - | `@ammaratef45:matrix.org` |
@@ -100,6 +100,8 @@ Recap:

 ### decision-making process

+proposal: https://git.coopcloud.tech/Federation/Federation/wiki/Proposals
+
 - Trav: We adapted an old proposal for descision making process.
 - https://pad.autonomic.zone/s/MLafJE2jC#Overview
 - https://coopcloud.tech/blog/federation-proposal/
@@ -1,6 +1,4 @@
---
-title: "Resolution 025 Maintainers Proposal"
---
+# Resolution 025 Maintainers Proposal

 - Topic:  Maintainers Proposal
 - Date: 05-12-2024
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 026: Budget 014: Backpay for v0.10.x abra release work"
+title: "Resolution 026"
 ---

 - Topic: Budget 014: Backpay for `v0.10.x` abra release work
@@ -1,33 +0,0 @@
---
-title: "Resolution 033: Changing OpenCollective fiscal host"
---
-
- Topic: Changing OpenCollective fiscal host to Platform6
- Date: 2025-07-16
- Deadline: 2025-07-30
- Size: Large
-
-## Summary
-
-Currently, the Open Collective "fiscal host" for Co-op Cloud is [Autonomic
-co-operative](https://autonomic.zone).
-
-This resolution proposes switching fiscal host to [Platform
-6](https://platform6.coop), by transferring our funds from Autonomic to
-Platform 6, and changing our registered fiscal host on Open Collective.
-
-This resolution will close Budget 001, because Platform 6 will take a fixed 5%
-of income, instead of being paid hourly.
-
-## Details
-
-Autonomic has been the fiscal host for Co-op Cloud since the first project
-funding was received.
-
-Since then, Autonomic has less capacity for finance administration work -- and
-Co-op Cloud is now managed by a democratic federation.
-
-So, to open up more capacity for project finance administration work, and to
-further decentralise Co-op Cloud organising from Autonomic, we're proposing
-Platform 6. Platform 6 have been fiscal host for co-operative projects
-including [meet.coop](https://meet.coop) and [wiki.cafe](https://wiki.cafe).
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 001: Decision-Making Process"
+title: "Resolution 001"
 ---

 - Topic: Decision Making Process
@@ -13,13 +13,13 @@ Institute descision making process as per below. Special consensus voting in org

 ### Decision Making Process

-* Write up a proposal using the below template, and add to the [Resolutions documentation "in-progress" section](https://docs.coopcloud.tech/federation/resolutions/).
+* Write up a proposal using the below template, and add to the [Proposals wiki page](https://git.coopcloud.tech/Federation/Federation/wiki/Proposals).
 * Specify if they are a large or medium proposal
 * Votes are done via emoji-reaction in the Community Organising Matrix channel (<https://matrix.to/#/#coopcloud-comm-org:autonomic.zone>)
+* List the decision on the [decisions page](https://docs.coopcloud.tech/federation/resolutions) on our documentation
 * Decisions can be split intro three categories: Small, Medium and Large.
 * Votes can be in favour :+1:, against :-1: (block),  or abstain :shrug:
 * Announce the result in the [Federation chat (#coop-cloud-fedi:autonomic.zone)](https://docs.coopcloud.tech/intro/contact/#matrix) and record it on the [decisions page](https://docs.coopcloud.tech/federation/resolutions) of the documentation
-* Move it to the [Resolutions documentation "passed" section](https://docs.coopcloud.tech/federation/resolutions/).

 ### Types of Proposals

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 002: Membership/Dues"
+title: "Resolution 002"
 ---

 * Topic: Membership/Dues
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 003: Paid Work"
+title: "Resolution 003"
 ---

 * Topic: Paid work
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 004: Budgeting (+ Budget 001: Monlthy Meetings)"
+title: "Resolution 004"
 ---

 * Topic: Budget 001: Budgeting
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 005: Public federation membership"
+title: "Resolution 005"
 ---

 * Topic: Public federation membership, notes and decisions
@@ -18,4 +18,4 @@ The following federation info will be made public on [`docs.coopcloud.tech/feder

 ### Details

-This will make the process of documenting easier to mutualise and increase transparency for those interested in joining. The `git.coopcloud.tech/Federation` wiki (**NOTE(d1) from the future**: this repository is now decommissioned) can still be used for storing private details such as bank account information. If members do not want to be listed, they can do so even when this decision passes.
+This will make the process of documenting easier to mutualise and increase transparency for those interested in joining. The [`git.coopcloud.tech/Federation`](https://git.coopcloud.tech/Federation/Federation/wiki/) wiki can still be used for storing private details such as bank account information. If members do not want to be listed, they can do so even when this decision passes.
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 006: Budget 002 Resolution Writing-up"
+title: "Resolution 006"
 ---

 - Budget 002: Resolution Writing-up
@@ -11,7 +11,7 @@ title: "Resolution 006: Budget 002 Resolution Writing-up"

 Agree Budget 002, for €100 for @decentral1se to write up 2 resolutions.

-### Details (Budget 002)
+### Details (Budget YYY)

 **Budget amount**: EUR 100

@@ -1,5 +1,5 @@
 ---
-title: "Resolution 007: Dues waiver for Doop.coop"
+title: "Resolution 007"
 ---

 - Topic: 1 year dues waiver for Doop.coop
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 008: Budget 003 Paying Invoices"
+title: "Resolution 008"
 ---

 - Topic: Budget 003 Paying invoices
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 009: Federation common fund buffer" 
+title: "Resolution 009" 
 ---

 - Topic: Federation common fund buffer
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 010: Budget 004 Critical fixes"
+title: "Resolution 010"
 ---

 - Topic: Budget 004: Critical fixes
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 011: Budget 005: Backup improvements" 
+title: "Resolution 011" 
 ---

 - Topic: Budget 005: Backup improvements
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 012: Budget 006: Abra integration test suite"
+title: "Resolution 012"
 ---

 - Budget 006: Abra integration test suite
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 014: Budget 008: Critical Fixes"
+title: "Resolution 014"
 ---

 - Topic: Budget 008: Critical Fixes
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 015: Klasse and Methode joins"
+title: "Resolution 015"
 ---

 - Topic: Klasse & Methode joins the Co-op Cloud Federation
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 016: Budget 008: Backup-bot-two …"
+title: "Resolution 016"
 ---

 - Topic: Budget 008: Backup-bot-two Documentation and Specification
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 017: BeWater joins"
+title: "Resolution 017"
 ---

 - Topic: BeWater joins the Co-op Cloud Federation
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 018: EOTL joins"
+title: "Resolution 018"
 ---

 - Topic: EOTL joins the Co-op Cloud Federation
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 019: Karrot joins"
+title: "Resolution 019"
 ---

 - Topic: Karrot joins the Co-op Cloud Federation
@@ -1,8 +1,8 @@
 ---
-title: "Resolution 020: Budget 010: Abra integration test suite"
+title: "Resolution 020"
 ---

- Topic: Budget 010: Abra integration suite automation
+- Topic: Budget 10: Abra integration suite automation
 - Date: 04-04-2024
 - Deadline: 18-04-2024
 - Size: Large
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 021: Budget 011: Migrate to Cobra"
+title: "Resolution 021"
 ---

 - Topic: Budget 011: Migrate to Cobra
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 022: Ammar joins"
+title: "Resolution 022"
 ---

 - Topic: Ammar joins the Co-op Cloud Federation
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 023: Budget 012: … new Co-op Cloud website"
+title: Resolution 023
 ---

 - Topic: Budget 012: Feedback gathering and content architecture for the new Co-op Cloud website
@@ -1,6 +1,4 @@
---
-title: "Resolution 024: Budget: 013: Reintroduce kite-flying"
---
+# Resolution 024: Budget: 013: Reintroduce kite-flying

 - Topic: Reintroduce paid kite-flying hour
 - Date: 2024-10-30
@@ -1,22 +0,0 @@
---
-title: "Resolution 027: MIR joins"
---
-
- 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 💖
@@ -1,17 +0,0 @@
---
-title: "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/
@@ -1,76 +0,0 @@
---
-title: "Resolution 029: Budget 014: 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.
@@ -1,41 +0,0 @@
---
-title: "Resolution 031: Critical fixes amended process"
---
-
- 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.
@@ -1,22 +0,0 @@
---
-title: "Resolution 032: RIM joins"
---
-
- Topic: RTM joins Coopcloud
- Date: 2025-06-30
- Deadline: 2025-07-10
- Size: Large
-
-### Summary
-
-Ammar's membership was approved in [Resolution 022](/federation/resolutions/passed/022).
-
-Since the establishment of RTM (Resist Rech Monopolies) collective in Seattle, Ammar has been unofficially representing the collective with coopcloud and vice versa.
-	
-### Details
-	
-RTM relies on the coop-cloud stack to host and manage their infrastructure, with the possibility of expanding this infrastructure to serve other communities and groups as the needs are identified and the capacity of the collective grows.
-
-In a loomio decision, the collective approved pursuing a membership with the federation and Ammar is both happy to vouch and to yield their membership to the group.
-
-This way this decision doesn't affect the total number of members.
@@ -1,5 +1,5 @@
 ---
-title: "Resolution 013: Budget 007: Operator sync" 
+title: "Resolution 013" 
 ---

 !!! note
@@ -1,37 +0,0 @@
---
-title: "Co-op Cloud resolution 030: Budget XXX: 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
@@ -3,10 +3,9 @@ title: Digital tools
 ---

 - [Public documentation](https://docs.coopcloud.tech/federation)
+- [Organising repository (private)](https://git.coopcloud.tech/Federation/organising)
+- [Wiki (private)](https://git.coopcloud.tech/Federation/organising/wiki)
 - [Git hosting](https://git.coopcloud.tech/)
 - [Matrix Space](https://matrix.to/#/#coop-cloud-space:autonomic.zone)
 - [Website](https://coopcloud.tech/)
- [Single Sign On](https://translate.coopcloud.tech/)
- [Translation](https://translate.coopcloud.tech/)
- [Sheets and time tracking](https://sheets.coopcloud.tech/)
 - [Drone CI/CD](https://build.coopcloud.tech)
@@ -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: [`toolshed/projects`](https://git.coopcloud.tech/toolshed/-/projects).
+- What we're currently working on is listed on this issue tracker: [`coop-cloud/organising`](https://git.coopcloud.tech/coop-cloud/organising/issues).
@@ -8,10 +8,12 @@ Co-op Cloud aims to make hosting libre software apps simple for small service pr

 ## Who is behind the project?

-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.
+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.
+

 ## Why Co-op Cloud?

@@ -2,7 +2,5 @@
 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)
+* [Dmytri Kleiner: "You can't code away their wealth"](https://yewtu.be/watch?v=FEU632_Em3g). Also, [The Telekommunist Manifesto](https://www.networkcultures.org/_uploads/%233notebook_telekommunist.pdf). Reading / checking out Kleiners work is a must IMHO -- `@decentral1se`.
+* [CoopCycle](https://coopcycle.org/en/) - heavily inspired the Federation model and how we shaped the first decisions on how to do it. -- `@decentral1se`
@@ -4,14 +4,11 @@ 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 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 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.

-*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.
+The Co-op Cloud is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: but you can still work with a tech co-op or collective to host some part or all of your online digital services with it. Organisations who want to support the project can get in touch with Co-op Cloud service providers via the following list for a quote on what they're looking for and how much it will cost. Service providers can then factor in some percentage of the cost to co-fund the development of this project.

 - [Autonomic Co-op](https://autonomic.zone) (contact: [`helo@autonomic.zone`](mailto: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))
+- [Solisoft](https://solisoft.top) (contact [`contact@solisoft.top`](mailto:contact@solisoft.top))
@@ -6,21 +6,23 @@ From our experiences working and organising as Autonomic, the tech co-op who [in

 ## Technological Saviors?

-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.
+The urgency to build an alternative is based on an analysis of our current reality.

-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.
+The monopolisation of our digital lives, the stranglehold of corporate control (aka [GAFAM](https://degooglisons-internet.org/en/)), represents a grave threat to our collective freedom, our societies and our hopes for a good life on planet earth.

-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.
+We begin with an acknowledgment of their vast accumulation of network effects and resources. We also acknowledge that no single project, product or organisation can create the required shift to a more widespread public interest technology.

-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.
+> Technology alone will not save us.
+>
+> Simply deploying libre software is not enough. 

-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.
+Our strategy is to mutualise our resources to facilitate this shift.

 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 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 collective liberation.

 We propose to go beyond a reductive technological vision of social change.

@@ -1,95 +0,0 @@
---
-title: The Recipe Catalogue
---
-
-## How are new recipes added to the catalogue?
-
-> This is so far a manual process which requires someone who's been added to the
-> `coop-cloud` "Organisation" on https://git.coopcloud.tech. 
->
-> This is a temporary  situation, we want to open out this process & also introduce some automation 
-> to support making thie process more convenient. Please nag us to move things along on Matrix.
-
- Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation"
- Run `abra catalogue generate <recipe> -p`
- Run `cd ~/.abra/catalogue && make`
-
-These minimal steps will publish a new recipe with no versions. You can also do
-the [recipe release publishing dance](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-release-a-new-recipe-version)
-which will then extend the `versions: [...]` section of the published JSON in the catalogue.
-
-Recipes that are not included in the catalogue can still be deployed. It is not
-required to add your recipes to the catalogue, but this will improve the
-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/toolshed/organising/issues/139).
-
-## How do I make the catalogue automatically regenerate after new recipe 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)
-(probably [using `abra recipe
-release`](#how-do-i-release-a-new-recipe-version)), it automatically does the
-[recipe catalogue generation steps](#how-do-i-generate-the-recipe-catalogue)"
-
-1. Check whether tag builds are already trying to run: go to
-   https://build.coopcloud.tech, search for the recipe name (in this case taking
-   you to https://build.coopcloud.tech/coop-cloud/rallly/settings). If there are
-   failing builds, or if you see builds succeeding but catalogue regeneration
-   doesn't seem to be happening, then either dive in and try and fix it, or ask
-   for help in [`#coopcloud-tech`](https://matrix.to/#/#coopcloud-tech:autonomic.zone)
-2. Otherwise, click "activate repository". You probably want to set the "disable pull
-   requests" and "disable forks" options; they won't work anyway, but the
-   failures might be confusing.
-3. Make sure there is a `generate recipe catalogue` step in the recipe's
-   `.drone.yml` -- if there isn't, you can copy [the one from
-   `coop-cloud/rallly`](https://git.coopcloud.tech/coop-cloud/rallly/src/branch/main/.drone.yml#L24-L38) unchanged.
-4. That's it! Now, when you push a new tag, the recipe catalogue will regenerate
-   automatically. You can test this by re-pushing a tag (e.g. `git push origin
-   :0.5.0+3.5.1 && git push 0.5.0+3.5.1`)
-
-## How does automatic catalogue regeneration work?
-
-**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 manually generate the recipe catalogue
-
-> These days, doing this is only useful in the event of troubleshooting the automatic catalogue regeneration
-
-To generate an entire new copy of the catalogue:
-
-```
-abra catalogue generate
-```
-
-You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
-
-If you just want to generate a catalogue entry for a single recipe:
-
-```
-abra catalogue generate <recipe>
-```
-
-The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
-
-```
-cd ~/.abra/catalogue
-git diff
-```
-
-You can pass `--publish` to have `abra` automatically publish those changes.
-
-!!! warning "Here be more SSH dragons"
-
-    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.
-
@@ -256,20 +256,6 @@ file_env "DB_PASSWORD"
 Sometimes the containers don't even have Bash installed on them. You had better just use `/bin/sh` or, in your entrypoint script, install Bash :upside_down: The entrypoint secrets hack listed above doesn't work in this case (as it requires Bash), so instead you can just do `export FOO=$(cat /run/secrets/<secret-name>)`.


-## Templating
-
-### Templating domain names in the `.env.sample`
-
-`<recipe>.example.com` will be transformed into the end-user app domain when `abra app new` is run.
-
-### Templating domain names in release notes
-
-!!! warning "Watch out for old versions of `abra` 🚧"
-
-    This feature is only available in the >= 0.11.x series of `abra`.
-
-`<recipe>.example.com` will be transformed into the end-user app domain when `abra app upgrade` shows release notes.
-
 ## How do I reference services in configs?

 When referencing an `app` service in a config file, you should prefix with the `STACK_NAME` to avoid namespace conflicts (because all these containers sit on the traefik overlay network). You might want to do something like this `{{ env "STACK_NAME" }}_app` (using  the often obscure dark magic of the Golang templating language). You can find examples of this approach used in the [Peertube recipe](https://git.coopcloud.tech/coop-cloud/peertube/src/commit/d1b297c5a6a23a06bf97bb954104ddfd7f736568/nginx.conf.tmpl#L9).
@@ -388,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. [We are working on improving this](https://git.coopcloud.tech/toolshed/-/projects/31).
+This is currently a manual process. Our best estimates are to do a backup and run a test deployment and see how things go.

 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.

@@ -400,19 +386,6 @@ It is good practice to take note of all the issues you ran into and share them w

 If you don't have time or are not an operator, reach out on our communication channels for an operator willing to do some testing.

-## What does "only updates to Labels are allowed" mean
-
-If you see something like this:
-
-```
-FATA failed to update config traefik_traefik_yml_v22: Error response from daemon: rpc error: code = InvalidArgument desc = only updates to Labels are allowed
-```
-
-It means that a Docker "config" has been updated, but the version number has not been incremented.
-
-To fix this, edit a recipe's `abra.sh` and update the version number of the relevant line –in this case, `export TRAEFIK_YML_VERSION=v22`.
-`
-
 ## How do I write version release notes?

 In the root of your recipe repository, run the following (if the folder doesn't already exist):
@@ -425,34 +398,72 @@ And then create a text file which corresponds to the version release, e.g. `1.1.

 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` 🚧"
+!!! warning "Not available previous versions of Abra"

-    This feature is only available in the >= 0.9.x series of `abra`.
+    Using `release/next` is only available in > 0.9.x series of `abra`.

-## How do I know whether to accept version upgrades when running `abra recipe upgrade <something>`?
+## How do I generate the recipe catalogue

-### Postgres
+To generate an entire new copy of the catalogue:

-Beware major Postgres version updates!
+```
+abra catalogue generate
+```

-"Major" updates are ones where the first number changes, for example 14 to 15 (or 14.1 to 15.1).
+You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.

-Postgres cannot update itself, so accepting major version upgrades can break existing app deployments.
+If you just want to generate a catalogue entry for a single recipe:

-To check if a recipe can handle upgrades:
+```
+abra catalogue generate <recipe>
+```

-1. Check whether the recipe is using the `pgautoupgrade` image.
-2. Check whether the recipe contains a custom postgres entrypoint, `entrypoint.postgres.sh`.
+The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:

-If neither #1 nor #2 is true, **do not include a "major" postgres upgrade in a recipe upgrade**.
+```
+cd ~/.abra/catalogue
+git diff
+```

-Feel welcome to ask for help in #coopcloud-tech:matrix.autonomic.zone
+You can pass `--publish` to have `abra` automatically publish those changes.
+
+!!! warning "Here be more SSH dragons"
+
+    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? 
+
+"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)
+(probably [using `abra recipe
+release`](#how-do-i-release-a-new-recipe-version)), it automatically does the
+[recipe catalogue generation steps](#how-do-i-generate-the-recipe-catalogue)"
+
+1. Check whether tag builds are already trying to run: go to
+   https://build.coopcloud.tech, search for the recipe name (in this case taking
+   you to https://build.coopcloud.tech/coop-cloud/rallly/settings). If there are
+   failing builds, or if you see builds succeeding but catalogue regeneration
+   doesn't seem to be happening, then either dive in and try and fix it, or ask
+   for help in [`#coopcloud-tech`](https://matrix.to/#/#coopcloud-tech:autonomic.zone)
+2. Otherwise, click "activate repository". You probably want to set the "disable pull
+   requests" and "disable forks" options; they won't work anyway, but the
+   failures might be confusing.
+3. Make sure there is a `generate recipe catalogue` step in the recipe's
+   `.drone.yml` -- if there isn't, you can copy [the one from
+   `coop-cloud/rallly`](https://git.coopcloud.tech/coop-cloud/rallly/src/branch/main/.drone.yml#L24-L38) unchanged.
+4. That's it! Now, when you push a new tag, the recipe catalogue will regenerate
+   automatically. You can test this by re-pushing a tag (e.g. `git push origin
+   :0.5.0+3.5.1 && git push 0.5.0+3.5.1`)
+
+## How does automatic catalogue regeneration work?
+
+TODO

 ## 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 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.
+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.

 You'll often find the same one used for things like caches & supporting services, such as Redis:

@@ -503,35 +514,6 @@ If you want to get the highest rating on SSL certs, you can use the following tr

 See [this PR](https://git.coopcloud.tech/coop-cloud/traefik/pulls/8/files) for the technical details

-## How do I skip secret generation for a specific secret
-
-!!! warning "Watch out for old versions of `abra` 🚧"
-
-    This feature is only available in the >= 0.11.x series of `abra`.
-
-Add the `# generate=false` comment
-
-```
-SECRET_JWT_SECRET_VERSION=v1 # generate=false
-```
-
-## How do I specify the charset for a specific secret generation
-
-!!! warning "Watch out for old versions of `abra` 🚧"
-
-    This feature is only available in the >= 0.10.x series of `abra`.
-
-```
-SECRET_JWT_SECRET_VERSION=v1 # charset=default,special
-```
-
-Options are:
-* `default`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L23)
-* `special`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L22C29-L22C43)
-* `safespecial`: [source](https://git.coopcloud.tech/toolshed/abra/src/commit/6abaf7a094df1a96599af2c4cbae1769821ad17c/pkg/secret/secret.go#L182)
-* `default,special`: mix of `default` and `special`
-* `default,safespecial`: mix of `default` and `safespecial`
-
 ## How do I change secret generation length?

 It is possible to tell `abra` which length it should generate secrets with from your recipe config.
@@ -551,31 +533,29 @@ 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?
+## How are recipes added to the catalogue?

-It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
+> This is so far a manual process which requires someone who's been added to the
+> `coop-cloud` "Organisation" on https://git.coopcloud.tech. This is a temporary
+> situation, we want to open out this process & also introduce some automation
+> to support making thie process more convenient. Please nag us to move things
+> along.

-You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
+- Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation"
+- Run `abra catalogue generate <recipe> -p`
+- Run `cd ~/.abra/catalogue && make`

-Here are some examples:
+These minimal steps will publish a new recipe with no versions. You can also do
+the [recipe release publishing dance](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-release-a-new-recipe-version)
+which will then extend the `versions: [...]` section of the published JSON in the catalogue.

-```bash
-SECRET_ADMIN_INIT_PASSWORD_VERSION=v1 # length=64 charset=default,safespecial
-SECRET_SERVICE_PASSWORD_VERSION=v1 # length=64 charset=default,special
-```
+Recipes that are not included in the catalogue can still be deployed. It is not
+required to add your recipes to the catalogue, but this will improve the
+visibility for other co-op hosters & end-users.

-The possible Values are:
+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.

-|                    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.
+In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).

 ## How do I configure backup/restore?

@@ -702,11 +682,6 @@ 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.

@@ -50,7 +50,7 @@ Open the `compose.yml` in your favourite editor and have a gander &#129442;. The
 5. The MariaDB service doesn't need to be exposed to the internet, so we can define an `internal` network for it to communicate with Matomo.
 6. Lastly, we want to use `deploy.labels` and remove the `ports:` definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.

-The resulting `compose.yml` is available [here](https://git.coopcloud.tech/coop-cloud/matomo/src/branch/main/compose.yml).
+The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).

 ### Updating the `.env.sample`

@@ -87,7 +87,7 @@ Otherwise, or once you've done that, go ahead and deploy the app:
 abra app deploy swarm.example.com
 ```

-Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables, if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.coopcloud.tech/coop-cloud/mediawiki) for examples of both).
+Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables, if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).

 ### Finishing up

@@ -94,29 +94,9 @@ git commit
 make link
 ```

-## Configure `abra` with `abra.yml`
-
-There are few configuration options supported at this time but more can be added. We are open to requests!
-
-### `$ABRA_DIR`
-
-The lookup logic is defined like so.
-
-* lookup $ABRA_DIR env
-* look for config file and take value from there
-* $HOME/.abra as fallback
-
-If you create an `abra.yml` file in your `$PWD` with the following contents.
-
-```
-abraDir: .
-```
-
-Then `$ABRA_DIR` will be automatically picked up as `$PWD`. This is useful when you maintain multiple project configurations and recipes in various state of chaos and would like to separate those. `abra` will create all the usual `$HOME/.abra` state (`servers`/`recipes`/etc.) under your chosen `abraDir` value. This allows you to have multiple independent versions of specific recipes which are relevant for specific projects vs. relying on a single `$ABRA_DIR/recipes/<recipe>` and constantly having to switch between different chaotic hacks.
-
 ## Running abra server side

-If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local computer.
+If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local work station.

 To install `abra` on the same server where you'll be hosting your apps, just follow [getting started guide](/operators/tutorial#deploy-your-first-app) as normal except for one difference. Instead of providing your SSH connection details when you run `abra server add ...`, just pass `--local`.

@@ -126,7 +106,7 @@ abra server add --local

 !!! note "Technical details"

-	This will tell `abra` to look at the Docker system running on the server itself, instead of a remote one (using the Docker internal `default` context). Once this is wired up, `abra` knows that the deployment target is the local server and not a remote one. This will be handled seamlessly for all other deployments on this server.
+	This will tell `abra` to look at the Docker system running on the server, instead of a remote one (using the Docker internal `default` context). Once this is wired up, `abra` knows that the deployment target is the local server and not a remote one. This will be handle seamlessly for all other deployments on this server.

 Make sure to back up your `~/.abra` directory on the server, or put it in version control, as well as other files you'd like to keep safe.

@@ -484,10 +464,6 @@ route requests after. You're free to make as many `$whatever.yml` files in your
 Yes, it's possible although currently Quite Experimental! See
 [`#388`](https://git.coopcloud.tech/toolshed/organising/issues/388) for more.

-## Can I deploy images from a private registry?
-
-Yes, as of [`#585`](https://git.coopcloud.tech/toolshed/abra/pulls/585), this is possible. At current time of writing, this feature is unreleased but this will change shortly. You need to run `docker login` before you run your deploy command.
-
 ## 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 ;-)
@@ -503,16 +479,16 @@ 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
+abra app secret insert localhost ssl_cert v1 "$(cat localhost.crt)"
+abra app secret insert localhost ssl_key v1 "$(cat localhost.key)"
 ```
 4. Re-deploy `traefik` with `--force` and voila!

 ## Remote recipes

-!!! warning "Watch out for old versions of `abra` 🚧"
+!!! warning "This is only available in the currently unreleased version of `abra`"

-    This feature is only available in the >= 0.10.x series of `abra`.
+    Please see [this issue](https://git.coopcloud.tech/toolshed/organising/issues/583) to track current progress towards a release. All feedback and testing are welcome on this new feature. The design is not finalised yet.

 It is possible to specify a remote recipe in your `.env` file:

@@ -530,9 +506,7 @@ $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`.
+!!! warning "This is only available in the currently unreleased version 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
@@ -553,13 +527,11 @@ 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 `--latest/-l`.
+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`.
+!!! warning "This is only available in the currently unreleased version of `abra`"

 ### `.env` version

@@ -569,31 +541,28 @@ 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 `--latest/-l`.
+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`)
+1. latest recipe version (standard `abra app deploy`)
+2. version retrieved from the app `.env` (`abra app deploy` + `TYPE=custom-html:1.7.1+1.27.2`)
+3. latest commit (`--chaos/-C` / `abra app deploy` + no released recipe versions)
+4. latest commit with unstaged changes (`abra app deploy --chaos/-C`)
+5. 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 `--latest/-l` to deploy the latest release version or commit.
+For 2), if the app **is undeployed** and there is an app `.env` version
+present, then it will be used. This is the *only time* the app `.env` version
+is used using `abra app deploy`. This is done to reduce unwanted upgrades (we
+do not automatically choose the latest release).

+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`
@@ -13,23 +13,23 @@ 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.

-We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html).
+### Server setup

-### Server provisioning
+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)).

-Co-op Cloud is designed to run on a variety of hardware, so you can use those single-board computers, old laptops/desktops, or refurbished servers. However, hardware setup is a skill that's beyond the scope of this guide. As long as it's running Linux and has networking, it should be fine! Most Co-op Cloud deployments have been run on Debian machines so far.
+We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html). You may also be interested in this [FAQ entry](/intro/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.

-If you don't have the time or equipment to run your own hardware, rented hardware is fine too! There are many hosting providers which will provide a Linux server to you for a monthly fee.
+Most Co-op Cloud deployments have been run on Debian machines so far. Some experiments have been done on single board computers & servers with low resource capacities.

-### Server configuration
+You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy ([Traefik](https://traefik.io)) keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.

-Assuming you've got a running server, it's now time to configure it.
+`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:

-Co-op Cloud has very few 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)).
+!!! warning "You may need to log in/out"

-To get started, you'll need to install Docker, add your user to the Docker group & setup swarm mode. Many hosting providers support [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html), which allows you to automate the steps in this section. If that applies to you, you can use [our cloud-init file](https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/cloud-init/cloud-init.yaml).
-
-Otherwise, here are the step required:
+    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.

 ```
 # ssh into your server
@@ -38,32 +38,24 @@ ssh <server-domain>
 # docker install convenience script
 wget -O- https://get.docker.com | bash

-# check that docker was installed correctly
-sudo docker run hello-world
-
-# now setup swarm
-sudo docker swarm init
-sudo docker network create -d overlay proxy
-```
-
-#### Using docker without sudo
-
-Abra can't deploy any applications in future steps unless it can run `docker` commands without sudo.
-
-```
-# check if the docker group exists
-groups | grep docker
-
-# if the docker group doesn't already exist, add it manually
-groupadd docker
-
 # add user to docker group
 sudo usermod -aG docker $USER
+
+# 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
 ```

-After running `usermod`, you may need to (depending on your system) log out (`exit`) and back in again (`ssh <server-domain>`) to get the required permissions for Docker before proceeding.
+??? question "Do you support multiple web proxies?"

-The [official Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/) can help if you run into further issues.
+    We do not know if it is feasible and convenient to set things up on an existing server with another web proxy which uses ports `:80` & `:443`. We'd happily receive reports and documentation on how to do this if you manage to set it up!

 ### DNS setup

@@ -76,17 +68,14 @@ 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 Beware local network pitfalls!
-
-    If you are in the same local network 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.

 ### 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/toolshed/abra/src/branch/main/scripts/installer/installer)):
+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/toolshed/abra/src/branch/main/scripts/installer/installer)):

 ```bash
 curl https://install.abra.coopcloud.tech | bash
@@ -99,7 +88,7 @@ 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
@@ -110,21 +99,15 @@ you have immediate access to `abra` on the current terminal.
 export PATH=$PATH:$HOME/.local/bin
 ```

-If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/toolshed/abra/issues/new) :pray:
+If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/toolshed/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.

 ??? 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 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 or use `abra server add -h` for the help output.
+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:"

@@ -138,24 +121,24 @@ Now you can connect `abra` with your server. You must have a working SSH configu
    troubleshooting entry](/abra/trouble/#ssh-connection-issues).

 ```bash
-ssh <server-domain> hostname -I # make sure it works
+ssh <server-domain> # make sure it works
 abra server add <server-domain>
 ```

-It is important to note that `<server-domain>` here is a publicly 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 ensure that your `Host ...` entry in your SSH configuration includes the name.  So, for example, in `~/.ssh/config`:
+    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:

-    ```
      Host example.com example
        ...
-    ```

    And then:

-      abra server add example
+      abra server add -D 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.

@@ -167,9 +150,8 @@ abra server ls

 ??? question "How do I share my configs in `~/.abra`?"

-    It's possible and relatively easy, for more see [this handbook
+    It's possible and quite easy, for more see [this handbook
    entry](/operators/handbook/#understanding-app-and-server-configuration).
-    [Git](https://git-scm.com) skills are generally required.

 ### Web proxy setup

@@ -177,15 +159,7 @@ In order to have your Co-op cloud deployment serve the public internet, we need

 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.
-
-You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.
-
-??? question "Do you support multiple web proxies?"
-
-   Yes, this is possible. See [this handbook
-   entry](/operators/handbook/#proxying-apps-outside-of-co-op-cloud-with-traefik)
-   for more. Be warned, this is a relatively advanced topic.
+features which make deploying libre apps more enjoyable. 

 **1. To get started, you'll need to create a new app:**

@@ -194,14 +168,12 @@ abra app new traefik
 ```

 Choose your newly registered server and specify a domain name. By default `abra`
-will suggest `<app-name>.<your-server>` or prompt you with a list of servers.
+will suggest `<app-name>.server.org` or prompt you with a list of servers.

-??? question "Should I use www for traefik?"
-    Generally no. No one will be directly accessing the traefik domain name unless they want to see the traefik dashboard. You should reserve the `www` or apex domains for apps like [custom-html](https://recipes.coopcloud.tech/custom-html-tiny) which let you host sites. Traefik is just a proxy to other apps!

 **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`:
+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`:

 ```bash
 abra app config <traefik-domain>
@@ -218,7 +190,7 @@ files exist at relevantly named path:
 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:
+it is deployed to, which is not ideal. You can disable this with:

 ```
 DASHBOARD_ENABLED=false
@@ -238,7 +210,7 @@ Voila. Abracadabra :magic_wand: your first app is deployed :sparkles:
 And now we can deploy apps. Let's create a new Nextcloud app.

 ```bash
-abra app new nextcloud --secrets
+abra app new nextcloud -S
 ```

 The `-S` or `--secrets` flag is used to generate secrets for the app: database connection password, root password and admin password.
@@ -247,7 +219,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.

-Now we can deploy Nextcloud:
+Then we can deploy Nextcloud:

 ```bash
 abra app deploy <nextcloud-domain>
@@ -261,7 +233,7 @@ abra app logs <nextcloud-domain>      # logs trailing
 abra app errors -w <nextcloud-domain> # error catcher
 ```

-Your new `traefik` instance will detect that a new app is coming up and generate TLS certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<nextcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
+Your new `traefik` instance will detect that a new app is coming up and generate SSL certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<netcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).

 ### Upgrade Nextcloud

@@ -6,7 +6,7 @@ backup/restore logic.

 ## Tools

-Two of the current "blessed" options are, which both implement the [backupbot specification](/specs/backup/spec/).
+Two of the current "blessed" options are, which both implement the [backupbot specification](link to spec)

 - [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two)
 - [`abra`](https://git.coopcloud.tech/toolshed/abra)
@@ -75,7 +75,6 @@ nav:
      - maintainers/index.md
      - "New Maintainers Tutorial": maintainers/tutorial.md
      - "Packaging Handbook": maintainers/handbook.md
-      - maintainers/catalogue.md
  - "Operators":
      - operators/index.md
      - "New operators Tutorial": operators/tutorial.md
@@ -88,7 +87,6 @@ nav:
      - "Finance": federation/finance.md
      - "Membership": federation/membership.md
      - "Code of Co-operation": federation/code-of-coop.md
-      - "Shared Infrastructure Inventory": federation/infra.md
      - "Proposals":
        - federation/proposals/index.md
        - federation/proposals/federation.md
@@ -118,19 +116,11 @@ nav:
              - 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
-              - federation/resolutions/passed/032.md
-              - federation/resolutions/passed/031.md
          - "Stalled":
              - federation/resolutions/stalled/013.md
-              - federation/resolutions/stalled/030.md
          - "In Progress":
-              - federation/resolutions/index.md
-              - federation/resolutions/in-progress/033.md
+              - federation/resolutions/in-progress/025.md
+              - federation/resolutions/in-progress/026.md
      - "Minutes":
          - federation/minutes/index.md
          - "Recently":
@@ -158,7 +148,7 @@ nav:
      - "Recipes": abra/recipes.md
      - "Hack": abra/hack.md
      - "Troubleshoot": abra/trouble.md
-      - "Cheat Sheet": abra/cheat-sheet.md
+      - "Cheat Sheet": abra/cheat-sheet.md       
  - "Specifications":
      - specs/index.md
      - "Backups":