Fix link to raise a ticket.

See coop-cloud/abra#255

Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:9.0.12
+FROM squidfunk/mkdocs-material:9.1.5
 
 EXPOSE 8000
 

docs/abra/cheat-sheet.md

@@ -49,3 +49,31 @@ flags: `-p/--publish`, `-r/--dry-run`, `-x,y,z`
 - deploy the changed version to your test instance
 - determine how serious your change is (semver.org for reference)
 - `abra recipe release $RECIPE [$VERSION]`
+
+### Advanced Listing using `jq`
+
+Several `abra` commands can output JSON formatted tables, and can thus be queried and filtered with the tool [jq](https://stedolan.github.io/jq/ "jq JSON Query tool"). We can also format these outputs with [tv](https://github.com/uzimaru0000/tv "tv Table Viewer") into a pretty table. 
+
+
+Currently, `abra recipe ls`, `abra server ls`, and `abra app ls` support the `-m` machine readable output flag which outputs JSON.
+
+#### Filter recipes by "category"
+
+`abra recipe ls -m | jq '[.[] | select(.category == "Utilities") ]' | tv`
+
+As you can see we, we're selecting all recipes where category is "Utilities".
+
+#### Filter apps by state `deployed`
+
+!!! info 
+    `abra app ls -S` queries each server in your added server list, where as without the `-S` it only lists from your local copy of the sever files (thus providing no information about actual state of the apps)
+
+!!! info 
+    `abra app ls` lists apps grouped into a server object, with statistics about the server. In `jq` we can select the entire apps list with `.[].apps[]`.
+
+`abra app ls -m -S |jq '[.[].apps[] | select(.status == "deployed") | del(.upgrade)]' |tv`
+
+The `del(.upgrade)` filter filters out available versions for the recipe in question for that row. It could be useful to leave in if you want a list of deployed apps that need an upgrade.
+
+
+

docs/abra/trouble.md

@@ -4,7 +4,7 @@ title: Troubleshoot
 
 ## Where do I report `abra` bugs / feature requests?
 
-You can use [this issue tracker](https://git.coopcloud.tech/coop-cloud/abra/issues/new).
+You can use [this issue tracker](https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose).
 
 ## SSH connection issues?
 
@@ -69,3 +69,11 @@ You can install it alongside the [supported version of Abra](https://git.coopclo
 git clone https://git.coopcloud.tech/coop-cloud/abra-bash ~/.abra/bash-src
 ln -s ~/.abra/bash-src/abra ~/.local/bin/babra
 ```
+
+## "Network not found" when deploying?
+
+This appears to be an upstream issue for which we can't do much in `abra` to solve. See [`coop-cloud/organising#420`](https://git.coopcloud.tech/coop-cloud/organising/issues/420) for more info. The work-around is to leave more time in between undeploy/deploy operations so the runtime can catch up.
+
+## 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.

docs/abra/upgrade.md

@@ -20,32 +20,17 @@ abra upgrade --rc
 
 ### `0.6.x-beta` -> `0.7.x-beta`
 
-> **ALERTA, ALERTA**: this is currently only available via the release
-> candidate channel, using `abra upgrade --rc`. There has been a lot of churn
-> and we're being cautious about releasing this one. Please help us test! We're
-> currently on `0.7.0-rc2-beta`.
-
-- `kadabra`, the app auto-updater is available for general alpha testing! See [these docs](https://docs.coopcloud.tech/operators/tutorial/#automatic-upgrades) for how to get started. Binaries can be found [here](https://git.coopcloud.tech/coop-cloud/abra/releases/tag/0.7.0-rc2-beta).
+> General release notes are [here](https://git.coopcloud.tech/coop-cloud/abra/releases/tag/0.7.0-beta)
 
 - **ALERTA, ALERTA**, security related issue: all `$domain.env` env vars are now exposed to the deployment via the `app` service container. Each `FOO=BAR` is exported within the context of the container. If you have any privately committed secrets in your `.env` files, please migrate them to the `secrets: ...` configuration in the recipe. This change was made to facilitate tooling which can support auto-upgrading of apps in a deployment.
 
 - `abra` can no longer install Docker, initialise swarm mode and the proxy network. It will check if a Docker install exists and is in swarm mode or not and error out accordingly. We leave the provisioning to tools that are designed for that and reduce the command-line surface that we have to maintain going forward.
 
-- `abra server add <host> <args>` 👉 `abra server add <host>`. We have finally removed the custom SSH handling code and now solely rely on invoke `/usr/bin/ssh` directly and reading from the `~/.ssh/config`. The `<host>` argument should correspond to a `Host <host>` entry in your `~/.ssh/config` or in an `Include <file>` statement (hosts are retrieved via `ssh -G <host>`). This means "how does `abra` interact with SSH is 1) do you have an `~/.ssh/config` entry for `<host>` 2) can you `ssh <host>` successfully? 3) there is no 3. It's an easier mental model and also the way `abra-bash` works, hence, less weird obscure errors. `<host>` being public a domain name is still required.
+- `abra server add <host> <args>` 👉 `abra server add <host>`. We have finally removed the custom SSH handling code and now solely rely on invoking `/usr/bin/ssh` directly and reading from the `~/.ssh/config`. The `<host>` argument should correspond to a `Host <host>` entry in your `~/.ssh/config` or in an `Include <file>` statement (hosts are retrieved via `ssh -G <host>`). This means "how does `abra` interact with SSH is 1) do you have an `~/.ssh/config` entry for `<host>` 2) can you `ssh <host>` successfully? 3) there is no 3. It's an easier mental model and also the way `abra-bash` works, hence, less weird obscure errors. `<host>` being public a domain name is still required.
 
 - `abra` no longer tries to do the TOFU host key verification prompt. We follow the praxis of the Docker CLI and just give up when host keys are not validated. We leave it to folks to SSH in and verify themselves.
 
-- On the way to [`kadabra`](https://git.coopcloud.tech/coop-cloud/abra/pulls/268), several changes regarding labelling deployments have been merged in this release. This will allow tooling to understand a deployment without having the context of a `~/.abra/...` configuration. This will pave the way for server-side tooling, like `kadabra` which can help operators with different kinds of maintenance tasks.
-
-- Welcome `abra recipe fetch`, which helps retrieve a recipe repository to your local work-station.
-
-- Also say hello to `abra app services <domain>`, which lists the in-deployment service names and corresponding image, e.g. `foo_example_com`.
-
-- Digests have been removed from the catalogue generation.
-
-- Backup files generated by `abra` have a much more human-friendly format.
-
-- Linting for domains is disabled when no `DOMAIN=...` is discovered in the `$odmain.env` file.
+- Digests have been removed from the catalogue generation. They are not being used elsewhere and were significantly slowing down generation.
 
 ### `0.5.x-beta` -> `0.6.x-beta`
 

docs/democracy/decisions.md

@@ -2,4 +2,60 @@
 title: Decisions
 ---
 
-Placeholder for all the wonderful decisions we will make together.
+## Proposal 001 - Desiscion Making Process - 2023-03-03
+
+- Deadline: 2023-03-03 (live voting)
+- Size: large
+
+### Summary 
+
+Institute descision making process as per below. Special consensus voting in organization meeting rather than the below process.
+
+### Decision Making Process
+
+* 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/democracy/decisions) 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/democracy/decisions) of the documentation
+
+### Types of Proposals
+
+#### Small - “Get on and do a thing”
+
+* Up to individual members to decide if they should just make the decision, or share it with the rest of the members to seek consensus.
+
+#### Medium - “consensus pending objections”
+
+* Potentially about shared tools, recipes, abra, etc.
+* Doesn’t have an effect on the direction or operation of Co-op Cloud as a whole.
+* If any member of Co-op Cloud thinks it’s a Large decision, achieve Maximum Consensus™ (see [below](https://pad.autonomic.zone/PtNbWo-7Tt-CKXvC6kxvZQ?view#Large---Maximum-Consensus-%E2%84%A2))
+* proposals must have a minimum deadline of 2 weeks from when they are proposed
+* Pass requirements:
+  * at least one :+1: vote
+  * no :-1: votes
+
+#### Large - “Maximum Consensus ™”
+
+* Important decisions affecting the operation, direction, working conditions and finances of Co-op Cloud.
+* proposals must have a minimum deadline of 2 weeks from when they are proposed
+* Pass requirements:
+  * more than 50% of total number of federation members :+1: votes
+  * no :-1: votes
+
+### Proposal Template
+
+```javascript
+## Proposal <number> - <title> - <date>
+
+- Deadline: Date
+- Size: large or medium
+
+### Summary
+Who this affects, and what it does
+
+### Details
+A narritive with details 
+```

docs/democracy/index.md

@@ -2,4 +2,4 @@
 title: Democracy
 ---
 
-Placeholder for all the wonderful things we will do together.
+The Co-op Cloud Federation is still bootstrapping. Here's what we know so far.

docs/intro/contact.md

@@ -12,14 +12,6 @@ title: Get in touch
 
 Here is a link to the [Matrix space](https://matrix.to/#/!xSMwGbdVehScXcIFwS:autonomic.zone?via=autonomic.zone&via=matrix.org&via=1312.media) to see all channels.
 
-- [`#coopcloud:autonomic.zone`](https://matrix.to/#/!JSVYWCRXSVMrAzgeKB:autonomic.zone?via=autonomic.zone) General chat and announcements (low traffic)
-- [`#coopcloud-tech:autonomic.zone`](https://matrix.to/#/!DfXPgKLoYCvjHithgS:autonomic.zone?via=autonomic.zone) Technical discussions (some techno babble)
-- [`#coopcloud-dev:autonomic.zone`](https://matrix.to/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Intense developer chat (a lot of techno babble)
-
-### XMPP
-
-> Coming Soon :tm:
-
 ## Forum
 
 [`community.coops.tech`](https://community.coops.tech/)

docs/intro/credits.md

@@ -6,7 +6,7 @@ title: Credits & thanks
 
 Special thanks to:
 
-- [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, and helping with OSX alpha testing.
+- [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, Matrix room avatars and helping with OSX alpha testing.
 - [Social.coop](https://social.coop), for warmly welcoming us onto [`social.coop/@coopcloud`](https://social.coop/@coopcloud).
 - [Servers.coop](https://servers.coop), for hosting our digital infrastructure (website, builds, git hosting, etc.).
 - Every single last one of you heroic & patient beta testers, you are all comrades of the highest order of kropotkin :heart:

docs/intro/faq.md

@@ -216,7 +216,7 @@ While the industry is bordering on a [k8s](https://kubernetes.io/) obsession and
 
 We hope to see a container orchestrator tool that is not directly linked to a for-profit company emerge soon but for now, this is what we have.
 
-If you want to learn more, see [dockerswarm.rocks](https://dockerswarm.rocks/) for a nice guide.
+If you want to learn more, see [dockerswarm.rocks](https://dockerswarm.rocks/) for a nice guide. See also [`BretFisher/awesome-swarm`](https://github.com/BretFisher/awesome-swarm).
 
 ## What licensing model do you use?
 

docs/maintainers/handbook.md

@@ -442,7 +442,7 @@ Best to [read](https://docs.docker.com/engine/reference/builder/#healthcheck) [t
 
 ## How do I tune resource limits?
 
-If you don't place resource limits on your app it will assume it can use the entire capacity of the server it is on. This can cause issues such as OOM eerors for your entire swarm.
+If you don't place resource limits on your app it will assume it can use the entire capacity of the server it is on. This can cause issues such as Out-Of Memory errors for your entire swarm.
 
 See the [Docker documentation](https://docs.docker.com/config/containers/resource_constraints/) to get into this topic and check the other recipes to see what other maintainers are doing.
 
@@ -457,7 +457,7 @@ 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 tweak secret generation length?
+## How do I change secret generation length?
 
 It is possible to tell `abra` which length it should generate secrets with from your recipe config.
 
@@ -622,7 +622,7 @@ cp -ar /app/client/dist /srv/client
 
 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. 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).
 

docs/operators/handbook.md

@@ -248,6 +248,10 @@ usermod -aG docker $USER
 # setup swarm
 docker swarm init
 docker network create -d overlay proxy
+
+# on debian machines as of 2023-02-17
+apt install apparmor
+systemctl restart docker containerd
 ```
 
 ## Managing DNS entries
@@ -341,7 +345,7 @@ See [`#312`](https://git.coopcloud.tech/coop-cloud/organising/issues/312) for mo
 
 ## How do I backup/restore my app?
 
-If you're app [supports backup/restore](/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/coop-cloud/abra).
+If you're app [supports backup/restore](/maintainers/handbook/#how-do-i-configure-backuprestore) then you have two options: [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) & [`abra`](https://git.coopcloud.tech/coop-cloud/abra).
 
 With `abra`, you can simply run `abra app backup ...` & `abra app restore ...`.
 Pass `-h` for more information on the specific flags & arguments.

docs/operators/tutorial.md

@@ -257,10 +257,7 @@ abra app upgrade <nextcloud-domain>
 
 ### Automatic Upgrades
 
-`kadabra` the auto-updater is still under development, use it with care and don't use it in production environments.
-To setup the auto-updater copy the `kadabra` binary to the server and configure a cronjob for regular app upgrades.
-The following script will configure ssmtp for email notifications and setup a cronjob.
-This cronjob checks daily for new app versions, notifies if any kind of update is available and upgrades all apps to the latest patch/minor version.
+`kadabra` the auto-updater is still under development, use it with care and don't use it in production environments. To setup the auto-updater copy the `kadabra` binary to the server and configure a cronjob for regular app upgrades. The following script will configure ssmtp for email notifications and setup a cronjob. This cronjob checks daily for new app versions, notifies if any kind of update is available and upgrades all apps to the latest patch/minor version.
 
 
 ```bash
@@ -283,12 +280,12 @@ MAILFROM=noreply@example.com
 30 4 * * *       root    ~/kadabra upgrade --all
 EOF
 
-
 ```
 
+Add `ENABLE_AUTO_UPDATE=true` to the env config (`abra app config <app name>`) to enable the auto-updater for a specific app.
 
 ## Finishing up
 
 Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.
 
-If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/coop-cloud/abra/issues/new) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.
+If not, please [get in touch](/intro/contact) or [raise a ticket](https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose) and we'll try to help out. We want our operator onboarding to be as smooth as possible, so we do appreciate any feedback we receive.

requirements.txt

@@ -1,4 +1,4 @@
 mkdocs-awesome-pages-plugin==2.8.0
 mkdocs-material-extensions==1.1.1
-mkdocs-material==9.0.12
+mkdocs-material==9.1.5
 mkdocs==1.4.2