Merge branch 'main' into R32

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

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)
 

docs/abra/hack.md

@@ -4,16 +4,20 @@ 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 💖 If any of your
-changes seems a bit controversial, it's probably to come have a chat first to
-avoid heartache.
+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 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
 
@@ -28,7 +32,7 @@ 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/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.
 
@@ -56,17 +60,13 @@ go test ./pkg/recipe -v -run TestGetVersionLabelLocalDoesNotUseTimeoutLabel
 
 ### Running on the CI server
 
-Based on
-[R020](https://docs.coopcloud.tech/federation/resolutions/passed/020/), we have
-automated running the integration test suite. Here's the TLDR;
+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 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.
+What follows is a listing of how this was achieved so that we can collectivise the maintenance.
 
 On the server, we have:
 
@@ -89,17 +89,13 @@ Please ask `@decentral1se` or on the Matrix channels for SSH access to the machi
 
 #### 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).
+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
@@ -110,10 +106,7 @@ sudo ./install.sh /usr/local
 
 #### Setup 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.
+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.
 
 ##### Remote swarm
 
@@ -122,9 +115,7 @@ 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.
-The test suite does not deploy Traefik for you.
+`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.
 
 ##### Local swarm
 
@@ -153,13 +144,12 @@ 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, we tag it as "slow". When the test
-requires public DNS, we use "dns". There may be more tags we write more tests.
+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,dns
@@ -168,18 +158,14 @@ requires public DNS, we use "dns". There may be more tags we write more tests.
 }
 ```
 
-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.
@@ -212,9 +198,7 @@ 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
 

docs/abra/index.md

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

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/toolshed/organising/issues/new/choose).
+You can use [this issue tracker](https://git.coopcloud.tech/toolshed/abra/issues/new).
 
 ## SSH connection issues?
 
@@ -83,3 +83,21 @@ 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
+```

docs/abra/upgrade.md

@@ -55,13 +55,10 @@ And test things work.
 
 ### `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
-  announcement
-  post](https://pad.local-it.org/G1TOcidEQtyArJU9gI0SDw?both#New-abra-release-candidate).
+  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.
@@ -114,6 +111,11 @@ 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.
 
@@ -128,6 +130,9 @@ 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.
+
 ### `0.8.x-beta` -> `0.9.x-beta`
 
 None at this time.

docs/federation/membership.md

@@ -16,6 +16,8 @@ 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` |
-| [BeWater](https://bewater.contact) | Waiver | - | `@decentral1se` |
+| `@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/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/in-progress/032.md

@@ -0,0 +1,22 @@
+---
+title: "Resolution 032"
+---
+
+- 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.

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/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?
 

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

@@ -2,5 +2,7 @@
 title: Inspirations
 ---
 
-* [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`
+* [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:boop@autonomic.zone))
-- [Local-IT](https://local-it.org/) (contact [`info@local-it.org`](mailto:info@local-it.org))
-- [Solisoft](https://solisoft.top) (contact [`contact@solisoft.top`](mailto:contact@solisoft.top))
+- [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/catalogue.md

@@ -0,0 +1,95 @@
+---
+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.
+

docs/maintainers/handbook.md

@@ -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.
 
@@ -398,72 +398,34 @@ 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 "Not available previous versions of Abra"
+!!! warning "Watch out for old versions of `abra` 🚧"
 
-    Using `release/next` is only available in > 0.9.x series of `abra`.
+    This feature is only available in the > 0.9.x series of `abra`.
 
-## How do I generate the recipe catalogue
+## How do I know whether to accept version upgrades when running `abra recipe upgrade <something>`?
 
-To generate an entire new copy of the catalogue:
+### Postgres
 
-```
-abra catalogue generate
-```
+Beware major Postgres version updates!
 
-You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
+"Major" updates are ones where the first number changes, for example 14 to 15 (or 14.1 to 15.1).
 
-If you just want to generate a catalogue entry for a single recipe:
+Postgres cannot update itself, so accepting major version upgrades can break existing app deployments.
 
-```
-abra catalogue generate <recipe>
-```
+To check if a recipe can handle upgrades:
 
-The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
+1. Check whether the recipe is using the `pgautoupgrade` image.
+2. Check whether the recipe contains a custom postgres entrypoint, `entrypoint.postgres.sh`.
 
-```
-cd ~/.abra/catalogue
-git diff
-```
+If neither #1 nor #2 is true, **do not include a "major" postgres upgrade in a recipe upgrade**.
 
-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
+Feel welcome to ask for help in #coopcloud-tech:matrix.autonomic.zone
 
 ## 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:
 
@@ -533,29 +495,31 @@ 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 are recipes added to the catalogue?
+## How do I change secret generation characters?
 
-> 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.
+It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
 
-- 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`
+You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
 
-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.
+Here are some examples:
 
-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.
+```bash
+SECRET_ADMIN_INIT_PASSWORD_VERSION=v1 # length=64 charset=default,safespecial
+SECRET_SERVICE_PASSWORD_VERSION=v1 # length=64 charset=default,special
+```
 
-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.
+The possible Values are:
 
-In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).
+|                    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 do I configure backup/restore?
 
@@ -682,6 +646,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.
 

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
 

docs/operators/handbook.md

@@ -336,13 +336,15 @@ cheetsheet](/abra/cheat-sheet/#manually-restoring-app-data).
 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:
@@ -351,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`?
@@ -476,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 "$(cat localhost.crt)"
-abra app secret insert localhost ssl_key v1 "$(cat localhost.key)"
+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 "This is only available in the currently unreleased version of `abra`"
+!!! warning "Watch out for old versions 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.
+    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:
 
@@ -503,7 +506,9 @@ $ABRA_DIR/recipes/mygit_org_myorg_cool-recipe
 
 ## Saving the version to the app `.env` file
 
-!!! warning "This is only available in the currently unreleased version of `abra`"
+!!! 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
@@ -528,7 +533,9 @@ with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
 
 ## How is the new deployment version determined?
 
-!!! warning "This is only available in the currently unreleased version of `abra`"
+!!! warning "Watch out for old versions of `abra` 🚧"
+
+    This feature is only available in the > 0.10.x series of `abra`.
 
 ### `.env` version
 
@@ -545,21 +552,24 @@ with `[version]` `--chaos/-C` or `--ignore-env-version/-i`.
 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 (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`)
+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.
 
-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).
+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`

docs/operators/tutorial.md

@@ -62,7 +62,7 @@ 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. 
+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?"
 
@@ -79,13 +79,7 @@ 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.
 
-On your local machine be sure to add your domain and all relevant subdomains in future steps to your `/etc/hosts` file. For example: 
-
-```
-116.203.211.204 example.com
-116.203.211.204 foo.example.com
-116.203.211.204 bar.example.com
-```
+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?"
 
@@ -107,7 +101,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
@@ -118,12 +112,18 @@ 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/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 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.
@@ -157,7 +157,7 @@ It is important to note that `<server-domain>` here is a publicy accessible doma
     ```
     And then:
 
-    `abra server add example`
+      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.
 
@@ -178,7 +178,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. 
+features which make deploying libre apps more enjoyable.
 
 **1. To get started, you'll need to create a new app:**
 
@@ -217,7 +217,7 @@ DASHBOARD_ENABLED=false
 
 **3. Now it is time to deploy your app:**
 
-Ensure `<traefic-domain>` is registered in `/etc/hosts` then run: 
+Ensure `<traefic-domain>` is registered in `/etc/hosts` then run:
 
 ```
 abra app deploy <traefik-domain>

docs/specs/backup/maintain.md

@@ -6,7 +6,7 @@ backup/restore logic.
 
 ## Tools
 
-Two of the current "blessed" options are, which both implement the [backupbot specification](link to spec)
+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)

mkdocs.yml

@@ -7,6 +7,7 @@ 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 2020-2024 Co-op Cloud
+copyright: Copyleft 2020-2025 Co-op Cloud
 
 markdown_extensions:
   - admonition
@@ -73,6 +75,7 @@ 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
@@ -114,11 +117,18 @@ 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
           - "Stalled":
               - federation/resolutions/stalled/013.md
           - "In Progress":
-              - federation/resolutions/in-progress/025.md
-              - federation/resolutions/in-progress/026.md
+              - federation/resolutions/index.md
+              - federation/resolutions/in-progress/030-docs-naming-survey.md
+              - federation/resolutions/in-progress/031.md
+              - federation/resolutions/in-progress/032.md
       - "Minutes":
           - federation/minutes/index.md
           - "Recently":
@@ -146,7 +156,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":

requirements.txt

@@ -1,16 +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