can switch between languages now

Closes coop-cloud/organising#400

Dockerfile

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

docs/abra/cheat-sheet.md

@@ -1,5 +1,5 @@
 ---
-tags: coop-cloud
+title: Cheat sheet
 ---
 
 # Abra cheat sheet

docs/abra/hack.md

@@ -20,17 +20,27 @@ Our [Drone CI configuration](https://git.coopcloud.tech/coop-cloud/abra/src/bran
 
 Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
 
+### Cross-compiling
+
+If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/coop-cloud/abra) and then:
+
+- enter the `abra` directory
+- run `git tag -l` to see the list of tags, choose the latest one
+- run `git checkout <tag>`, where `<tag>` is the latest version
+- run `GOOS=<os> GOARCH=<arch> [GOARM=<arm>] make build`. You only have to use `GOARM` if you're building for ARM, this specifies the ARM version (5,6,7 etc). See [this](https://go.dev/doc/install/source#environment) for a list of all supported OS'es and architectures.
+
+
 ## Release management
 
-We use [goreleaser](https://goreleaser.com) to help us automate releases. We use [semver](https://semver.org) for versioning all releases of the tool. While we are still in the public alpha release phase, we will maintain a `0.y.z-alpha` format. Change logs are generated from our commit logs. We are still working this out and aim to refine our release praxis as we go.
+We use [goreleaser](https://goreleaser.com) to help us automate releases. We use [semver](https://semver.org) for versioning all releases of the tool. While we are still in the public beta release phase, we will maintain a `0.y.z-beta` format. Change logs are generated from our commit logs. We are still working this out and aim to refine our release praxis as we go.
 
-For developers, while using this `-alpha` format, the `y` part is the "major" version part. So, if you make breaking changes, you increment that and _not_ the `x` part. So, if you're on `0.1.0-alpha`, then you'd go to `0.1.1-alpha` for a backwards compatible change and `0.2.0-alpha` for a backwards incompatible change.
+For developers, while using this `-beta` format, the `y` part is the "major" version part. So, if you make breaking changes, you increment that and _not_ the `x` part. So, if you're on `0.1.0-beta`, then you'd go to `0.1.1-beta` for a backwards compatible change and `0.2.0-beta` for a backwards incompatible change.
 
 ### Making a new release
 
 - Change `ABRA_VERSION` to match the new tag in [`scripts`](./scripts/installer/installer) (use [semver](https://semver.org))
-- Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-alpha'`)
-- Make a new tag (e.g. `git tag -a x.y.z-alpha`)
+- Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-beta'`)
+- Make a new tag (e.g. `git tag -a x.y.z-beta`)
 - Push the new tag (e.g. `git push && git push --tags`)
 - Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/coop-cloud/abra)
 - Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
@@ -45,3 +55,7 @@ We maintain a fork of [godotenv](https://github.com/Autonomic-Cooperative/godote
 ### `docker/client`
 
 A number of modules in [pkg/upstream](./pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.
+
+### `github.com/schultz-is/passgen`
+
+Due to [`coop-cloud/organising#358`](https://git.coopcloud.tech/coop-cloud/organising/issues/358).

docs/abra/index.md

@@ -4,7 +4,7 @@ title: Abra
 
 <a href="https://github.com/egonelbre/gophers"><img align="right" width="250" src="https://github.com/egonelbre/gophers/raw/master/.thumb/sketch/adventure/poking-fire.png"/></a>
 
-`abra` is our flagship client & command-line tool which has been developed specifically in the context of the Co-op Cloud project 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 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)).
 

docs/abra/install.md

@@ -17,3 +17,17 @@ curl https://install.abra.coopcloud.tech | bash -s -- --rc
 ## Installer script source
 
 You can view that [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).
+
+## Using Docker
+
+```
+docker run \
+	-v $HOME/.abra:/.abra \
+	git.coopcloud.tech/coop-cloud/abra app ls
+```
+
+!!! note
+	If you're using symlinks, e.g. for [sharing
+	`~/.abra`](/operators/handbook/#sharing-abra), add more `-v` options for each
+	directory you're symlinking to, e.g. `-v
+	$HOME/Projects/CoopCloud/apps:/home/user/Projects/CoopCloud/apps`

docs/abra/trouble.md

@@ -89,7 +89,7 @@ We're still waiting for upstream patch which resovles this.
 
 We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/coop-cloud/organising/issues/291) for more.
 
-## I need some feature from the old depreciated bash abra?
+## I need some feature from the old deprecated bash abra?
 
 There is an archive of the [old code here](https://git.coopcloud.tech/coop-cloud/abra-bash).
 
@@ -99,3 +99,7 @@ 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
 ```
+
+## I am seeing very weird `lookup <domain> on <ip>: write udp <ip>: write: operation not permitted` errors
+
+You should turn off your VPN. `abra` has trouble dealing with it right now. We welcome change sets to make it work though!

docs/abra/upgrade.md

@@ -18,6 +18,53 @@ abra upgrade --rc
 
 ## Migration guides
 
+### `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).
+
+- **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` 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.
+
+### `0.5.x-beta` -> `0.6.x-beta`
+
+- Using `{{ .Domain }}` in recipe `.envrc.sample` files went away because it
+  was portable enough. We revert to replacing e.g `gitea.example.com` with the
+  domain. See
+  [`8fad34e`](https://git.coopcloud.tech/coop-cloud/abra/commit/8fad34e) for
+  more.
+
+- If your `abra.sh` scripts depend on `/bin/sh` and `/bin/bash` is available in
+  the container then `/bin/bash` will be used from now on. `/bin/sh` is only
+  now used if `/bin/bash` is not available. See
+  [`7f745ff`](https://git.coopcloud.tech/coop-cloud/abra/commit/7f745ff) for
+  more.
+
+### `v0.4.x` -> `v0.5.x`
+
+- The only breaking change was making `abra` understand that the JSON dump for the recipes listing lives on [recipes.coopcloud.tech/recipes.json](https://recipes.coopcloud.tech) instead of [recipes.coopcloud.tech](https://recipes.coopcloud.tech).
+
 ### `v0.3.x` -> `v0.4.x`
 
 Make sure to back up your `~/.abra/servers` configurations first for safety.
@@ -28,6 +75,10 @@ Make sure to back up your `~/.abra/servers` configurations first for safety.
 
 - `abra` has a new SSH implementation which enforces SSH host key checking. You may run into connection issues as a result of this code churn, please see [this entry](/abra/trouble/#ssh-connection-issues) for help navigating a fix.
 
-- CLI flag/args handling has been made more flexible. We're workign within the constraints of an upstream library issue but have hopefully made it easier to mange passing flags to commands with `abra`. See [this troubleshooting entry](/abra/trouble/#command-line-flag-handling-is-weird) for the full review.
+- CLI flag/args handling has been made more flexible. We're working within the constraints of an upstream library issue but have hopefully made it easier to mange passing flags to commands with `abra`. See [this troubleshooting entry](/abra/trouble/#command-line-flag-handling-is-weird) for the full review.
 
 - A number of short style flags have been re-mapped and/or added. This is again related to an issue with the upstream CLI library which sometimes understands short style flags as long style flags. E.g. `--ch` instead of `-ch` for `--chaos`. As a concrete example, `--ch` is now `-C` on `abra app deploy`.
+
+- `abra app backup` & `abra app restore` are ready for alpha-testing! See [this entry](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-configure-backuprestore) and [that entry](https://docs.coopcloud.tech/operators/handbook/#how-do-i-backuprestore-my-app) for more.
+
+- `abra server add --traefik` went away, it was too unreliable & hard to maintain.

docs/get-involved/index.md

@@ -6,7 +6,7 @@ title: Get Involved
 
 > :trumpet: **You don't have to be a programmer to contribute to this project!** :trumpet:
 
-Firstly, come say hello in our [chat room](/intro/contact/) if you'd like to help out or re 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 :wave:
 
 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.
 

docs/glossary/index.md

@@ -40,7 +40,7 @@ A [Docker](glossary#docker) related concept: a virtual network created on the se
 
 ## Recipe
 
-A recipe is what we call the configuration files that are used to deploy an [app](/glossary#app). When you run `abra app deploy <domain>`, `abra` is reading a recipe configuration, such as [the gitea recipe](https://git.coopcloud.tech/coop-cloud/gitea), in order to know how to deploy a new Gitea instance. When we speak of a "digital configuraiton commons", we're primarily referring to the [growing collection of recipes](https://git.coopcloud.tech/coop-cloud).
+A recipe is what we call the configuration files that are used to deploy an [app](/glossary#app). When you run `abra app deploy <domain>`, `abra` is reading a recipe configuration, such as [the gitea recipe](https://git.coopcloud.tech/coop-cloud/gitea), in order to know how to deploy a new Gitea instance. When we speak of a "digital configuration commons", we're primarily referring to the [growing collection of recipes](https://git.coopcloud.tech/coop-cloud).
 
 ## Secret
 

docs/index.md

@@ -16,9 +16,9 @@ We'd be happy to hear feedback about our documentation, if it was helpful, what
 
 !!! danger "Here be dragons"
 
-    This project is still [alpha quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) :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](/get-involved/).
 
-- [Operators guide](/operators/): You run a Co-op Cloud deployment or want to do so :computer:
+- [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:
 

docs/index.pl.md

@@ -0,0 +1,33 @@
+---
+title: Wstęp
+---
+
+## Who is this for?
+
+Witaj w dokumentacji Co-op Cloud!
+
+Ta dokumentacja jest skierowana do odbiorców "technicznych": spółdzielni technologicznych, kolektywów i osób indywidualnych zainteresowanych Co-op Cloud, lub takich, które mają już deploymenty Co-op Cloud.
+
+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).
+
+We'd be happy to hear feedback about our documentation, if it was helpful, what was missing, what was confusing, etc., please [get in touch](/intro/contact)!
+
+## Quick start
+
+!!! 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/).
+
+- [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:
+
+- [Recipes](/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:
+
+- [Glossary](/glossary/): You'd like clarification about project terminology :book:

docs/intro/bikemap.md

@@ -2,8 +2,8 @@
 title: Bike map
 ---
 
-- The project is currently in an [alpha quality](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) release state.
+- The project is currently in a [beta quality](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) release state.
 
-- We are working towards a [beta release](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta). Our public Beta goals are listed in the following pad: [Beta Bike Map](https://pad.autonomic.zone/s/C3uuqfSCk).
+- 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.autonomic.zone/coop-cloud/organising/issues).

docs/intro/credits.md

@@ -9,5 +9,5 @@ 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.
 - [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 alpha/beta testers, you are all comrades of the highest order of kropotkin :heart:
+- Every single last one of you heroic & patient beta testers, you are all comrades of the highest order of kropotkin :heart:
 - [`egonelbre/gophers`](https://github.com/egonelbre/gophers) for the rad gopher logos

docs/intro/faq.md

@@ -178,7 +178,7 @@ We definitely recommend using best-in-class security auditing tools like [docker
 
 It's up to how you want to arrange your system. For example, Co-op Cloud also allows you to compartmentalise different apps onto different servers. You could stack a bunch of apps on one big server or you could deploy one app per server.
 
-These are organisational concerns that Co-op Cloud can't solve for you which any software system will require. See this [additional question](/faq/#what-is-important-to-consider-when-running-containers-in-production) for further information.
+These are organisational concerns that Co-op Cloud can't solve for you which any software system will require. See this [additional question](/intro/faq/#what-is-important-to-consider-when-running-containers-in-production) for further information.
 
 ## What is important to consider when running containers in production?
 

docs/intro/managed.md

@@ -6,6 +6,8 @@ title: Managed hosting
 
     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.
 
-The Co-op Cloud is still [alpha quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) :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:helo@autonomic.zone))
+- [Local-IT](https://local-it.org/) (contact [`info@local-it.org`](mailto:info@local-it.org))
+- [Solisoft](https://solisoft.top) (contact [`contact@solisoft.top`](mailto:contact@solisoft.top))

docs/maintainers/handbook.md

@@ -224,11 +224,11 @@ 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>)`.
 
 
-## Reference services in configs?
+## 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).
 
-## How are recipes are versioned?
+## How are recipes versioned?
 
 We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
 
@@ -364,7 +364,7 @@ mkdir -p releases
 
 And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
 
-## Generate the recipe catalogue
+## How do I generate the recipe catalogue
 
 To generate an entire new copy of the catalogue:
 
@@ -393,7 +393,7 @@ You can pass `--publish` to have `abra` automatically publish those changes.
 
     In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
 
-## Enable healthchecks
+## 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.
 
@@ -410,7 +410,7 @@ If you're just starting off with packaging a recipe, you can use `healthcheck: d
 
 `abra app errors -w <domain>` will show what errors are being reported from a failing healtcheck setup.
 
-## Tuning deploy configs
+## How do I tune deploy configs?
 
 A bit like healtchecks, there is no universal setup. A good default seems to be the following configuration:
 
@@ -431,13 +431,13 @@ Setting a restart policy is also good so that the runtime doesn't try to restart
 
 Best to [read](https://docs.docker.com/engine/reference/builder/#healthcheck) [the docs](https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck) on this one.
 
-## Tuning resource limits
+## 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.
 
 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.
 
-## Enable A+ SSL ratings
+## How do I enable A+ SSL ratings?
 
 If you want to get the highest rating on SSL certs, you can use the following traefik labels which use a tweaked Traefik configuration.
 
@@ -448,7 +448,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
 
-## Tweaking secret generation length
+## How do I tweak secret generation length?
 
 It is possible to tell `abra` which length it should generate secrets with from your recipe config.
 
@@ -466,3 +466,76 @@ When using this length specifier, `abra` will not use the "easy to remember
 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?
+
+> 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.
+
+- 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/coop-cloud/organising/issues/139).
+
+## How do I configure backup/restore?
+
+From the perspective of the recipe maintainer, backup/restore is just more
+`deploy: ...` labels. Tools can read these labels and then perform the
+backup/restore logic.
+
+### Tools
+
+Two of the current "blessed" options are
+[`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) &
+[`abra`](https://git.coopcloud.tech/coop-cloud/abra).
+
+#### `backup-bot-two`
+
+Please see the [`README.md`](https://git.coopcloud.tech/coop-cloud/backup-bot-two#backupbot-ii) for the full docs.
+
+#### `abra`
+
+`abra` will read labels and store backups in `~/.abra/backups/...`.
+
+### Backup
+
+For backup, here are the labels & some examples:
+
+- `backupbot.backup=true`: turn on backup logic
+- `backupbot.backup.pre-hook=mysqldump -u root -pghost ghost --tab /var/lib/foo`: command to run before backing up
+- `backupbot.backup.post-hook=rm -rf /var/lib/mysql-files/*`: command to run after backing up
+- `backupbot.backup.path=/var/lib/foo,/var/lib/bar`: paths to back up
+
+You place these on your recipe configuration and then tools can run backups.
+
+### Restore
+
+Restore, in this context means, "moving a compressed archive back to the
+container backup paths". So, if you set
+`backupbot.backup.path=/var/lib/foo,/var/lib/bar` and you have a backed up
+archive, tooling will unzip files in the archive back to those paths.
+
+In the case of restoring database tables, you can use the `pre-hook` &
+`post-hook` commands to run the insertion logic.
+
+## Can I override a service within a recipe?
+
+You can use [this `docker-compose` trick](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files) to do this.
+
+If you have a recipe that is using a `mysql` service and you'd like to use `postgresql` instead, you can create a `compose.psql.yml`!
+
+An example of this is the [`selfoss`](https://git.coopcloud.tech/coop-cloud/selfoss) recipe. The default is `sqlite` but there is a `postgresql` compose configuration there too.

docs/maintainers/tutorial.md

@@ -21,7 +21,7 @@ The idea scenario is when the upstream project provides both the packaged image
 - **Inspired**: Upstream image, someone else's compose file
 - **On fire**: Upstream image, upstream compose file
 
-### Writing the `compose.yml`
+### Writing / adapting the `compose.yml`
 
 Let's take a practical example, [Matomo web analytics](https://matomo.org/). We'll be making a Docker "swarm-mode" `compose.yml` file.
 
@@ -66,8 +66,8 @@ abra app new matomo --secrets \
  --server swarm.example.com
 ```
 
-Depending on whether you defined any extra environment variables, we didn't so
-far, in this example, you might want to run `abra app config swarm.example.com`
+Depending on whether you defined any extra environment variables -- we didn't so
+far, in this example -- you might want to run `abra app config swarm.example.com`
 to check the configuration.
 
 Otherwise, or once you've done that, go ahead and deploy the app:
@@ -80,4 +80,4 @@ Then, open the `DOMAIN` you configured (you might need to wait a while for Traef
 
 ### Finishing up
 
-You've probably got more questions, check out the [maintainers handbook](/maintainers/handbook)!
+You've probably got more questions, check out the [packaging handbook](/maintainers/handbook)!

docs/operators/handbook.md

@@ -82,6 +82,18 @@ Then, tell your collaborators (e.g. in the repository's `README.md`), to run `ma
 
     We don't currently recommend this, because it might set inaccurate expectations about the security model – remember that, by default, **any user who can deploy apps to a Docker Swarm can manage _any_ app in that swarm**.
 
+### Migrating a server into a repository
+
+Even if you've got your existing server configs in version control, by default, `abra server add` will define the server locally. To move it -- taking the example of `newserver.example.com`:
+
+```
+mv ~/.abra/servers/newserver.example.com ~/coop-cloud-apps/
+cd ~/coop-cloud-apps
+git add newserver.example.com
+git commit
+make link
+```
+
 ## 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 work station.
@@ -231,7 +243,7 @@ The requirements are:
 wget -O- https://get.docker.com | bash
 
 # add user to docker group
-usermod -aG docker $YOURUSERNAMEHERE
+usermod -aG docker $USER
 
 # setup swarm
 docker swarm init
@@ -267,7 +279,7 @@ You need to add the following to your `/etc/docker/daemon.json` file on the serv
 }
 ```
 
-And for log size management, edit `/etc/systemd/journal.conf`:
+And for log size management, edit `/etc/systemd/journald.conf`:
 
 ```
 [Journal]
@@ -312,6 +324,10 @@ Running `server add` with `-d/--debug` should help you debug what is going on un
 
 If you need to run a command within a running container you can use `abra app run <domain> <service> <command>`. For example, you could run `abra app run cloud.lumbung.space app bash` to open a new bash terminal session inside your remote container.
 
+## How do I attach on a non-running container?
+
+If you need to run a command on a container that won't start (eg. the container is stuck in a restart loop) you can temporarily disable its default entrypoint by setting it in `compose.yml` to something like ['tail', '-f', '/dev/null'], then redeploy the stack (with `--force --chaos` so you don't need to commit), then [get into the now running container](#how-do-i-attach-to-a-running-container), do your business, and when done revert the compose.yml change and redeploy again. 
+
 ## Can I run Co-op Cloud on ARM?
 
 `@Mayel`:
@@ -324,3 +340,50 @@ If you need to run a command within a running container you can use `abra app ru
 > or arm images
 
 See [`#312`](https://git.coopcloud.tech/coop-cloud/organising/issues/312) for more.
+
+## 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).
+
+With `abra`, you can simply run `abra app backup ...` & `abra app restore ...`.
+Pass `-h` for more information on the specific flags & arguments.
+
+## How do I take a manual database backup?
+
+MySQL / MariaDB:
+
+```
+abra app run foo.bar.com db mysqldump -u root <database> | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
+```
+
+Postgres:
+
+```
+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:
+- Make sure you've specified the right database user (`root` above) and db name
+- If you have a database password set, you might need to load it from a secret,
+    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
+```
+
+## Can I deploy a recipe without `abra`?
+
+Yes! It's a design goal to keep the recipes not dependent on `abra` or any
+single tool that we develop. This means the configurationc commons can still be
+useful beyond this project. You can deploy a recipe with standard commands like
+so:
+
+```
+set -a
+source example.com.env
+cd ~/.abra/recipes/myrecipe
+docker stack deploy -c compose.yml example_com
+```
+
+`abra` makes all of this more cenvenient but other tooling could follow this
+approach.

docs/operators/tutorial.md

@@ -94,9 +94,9 @@ The tutorial tries to help you make choices about which server and which DNS set
 
 ### Server setup
 
-Co-op Cloud has itself near zero system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/faq/#isnt-running-everything-in-containers-inefficient)).
+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)).
 
-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](/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.
+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.
 
 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.
 
@@ -109,7 +109,7 @@ You need to keep port `:80` and `:443` free on your server for web proxying to y
 wget -O- https://get.docker.com | bash
 
 # add user to docker group
-usermod -aG docker $YOURUSERNAMEHERE
+sudo usermod -aG docker $USER
 
 # setup swarm
 docker swarm init
@@ -211,7 +211,7 @@ Choose your newly registered server and specify a domain name.
 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
+abra app config <traefik-domain>
 ```
 
 Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required.
@@ -252,6 +252,46 @@ abra app errors -w <nextcloud-domain> # error catcher
 
 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
+
+To upgrade an app manually to the newest available version run:
+
+```bash
+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.
+
+
+```bash
+apt install ssmtp
+
+cat > /etc/ssmtp/ssmtp.conf << EOF
+mailhub=$MAIL_SERVER:587
+hostname=$MAIL_DOMAIN
+AuthUser=$USER
+AuthPass=$PASSWORD
+FromLineOverride=yes
+UseSTARTTLS=yes
+EOF
+
+cat > /etc/cron.d/abra_updater << EOF
+MAILTO=admin@example.com
+MAILFROM=noreply@example.com
+
+0  6 * * *       root    ~/kadabra notify --major
+30 4 * * *       root    ~/kadabra upgrade --all
+EOF
+
+
+```
+
+
 ## 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.

docs/recipes/index.md

@@ -15,6 +15,65 @@ It aims to be a helpful place to understand the status of apps, who is taking ca
 
 The recipe catalogue is available on [recipes.coopcloud.tech](https://recipes.coopcloud.tech/).
 
+## Status / features / scoring
+
+Each recipe README has a "metadata" section, to help communicate the overall status of the recipe, and which features are supported. Here's an example, from [the Wordpress recipe](https://git.coopcloud.tech/coop-cloud/wordpress/):
+
+```
+<!-- metadata -->
+
+* **Category**: Apps
+* **Status**: 3, stable
+* **Image**: [`wordpress`](https://hub.docker.com/_/wordpress), 4, upstream
+* **Healthcheck**: Yes
+* **Backups**: Yes
+* **Email**: 3
+* **Tests**: 2
+* **SSO**: No
+
+<!-- endmetadata -->
+```
+
+Currently, recipe maintainers need to update the scores in this section manually. The specific meanings of the scores are:
+
+### Status (overall score)
+
+- 5: everything in 4 + Single-Sign-On
+- 4: upstream image, backups, email, healthcheck, integration testing
+- 3: upstream image, missing 1-2 items from 4
+- 2: missing 3-4 items from 4 or no upstream image
+- 1: alpha
+
+### Image
+
+- 4: official upstream image
+- 3: semi-official / actively-maintained image
+- 2: 3rd-party image
+- 1: our own custom image
+
+### Email
+
+- 3: automatic (using environment variables)
+- 2: mostly automatic
+- 1: manual
+- 0: none
+- N/A: app doesn't send email
+
+### CI
+
+- 3: as 2, plus healthcheck
+- 2: auto secrets + networks
+- 1: basic deployment using `stack-ssh-deploy`, manual secrets + networks
+- 0: none
+
+### Single-Sign-On
+
+- 3: automatic (using environment variables)
+- 2: mostly automatic
+- 1: manual
+- 0: none
+- N/A: app doesn't support SSO
+
 ## Wishlist
 
 If you'd like to see a new recipe packaged, make a request on the [recipes-wishlist](https://git.coopcloud.tech/coop-cloud/recipes-wishlist) repository issue tracker.

mkdocs.yml

@@ -78,6 +78,20 @@ nav:
 plugins:
   - search
   - awesome-pages
+  - translations:
+      default_language: en
+      languages:
+        en: english
+        pl: polski
+
+extra:
+  alternate:
+    - name: English
+      link: /en/
+      lang: en
+    - name: Polish
+      link: /pl/
+      lang: pl
 
 repo_name: coop-cloud/docs.coopcloud.tech
 repo_url: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech

renovate.json

@@ -1,3 +1,7 @@
 {
-  "$schema": "https://docs.renovatebot.com/renovate-schema.json"
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "packageRules": [{
+    "matchUpdateTypes": ["minor", "patch"],
+    "automerge": true
+  }]
 }

requirements.txt

@@ -1,4 +1,5 @@
-mkdocs-awesome-pages-plugin==2.7.0
-mkdocs-material-extensions==1.0.3
-mkdocs-material==8.2.8
-mkdocs==1.3.0
+mkdocs-awesome-pages-plugin==2.8.0
+mkdocs-material-extensions==1.1.1
+mkdocs-material==9.0.12
+mkdocs==1.4.2
+mkdocs-translations>=0.1.1