Merge branch 'main' of ssh://git.coopcloud.tech:2222/coop-cloud/docs.coopcloud.tech

Dockerfile

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

docs/abra/upgrade.md

@@ -28,6 +28,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/intro/contact.md

@@ -13,7 +13,7 @@ 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/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Technical discussions (some techno babble)
+- [`#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

docs/intro/faq.md

@@ -249,3 +249,5 @@ Yes! Horizontal scaling is one of the ways Co-op Cloud can really shine. `abra`
 ## Why only x86 support?
 
 We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.autonomic.zone/coop-cloud/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](/intro/contact/).
+
+Update: [Can I run Co-op Cloud on ARM?](/operators/handbook/#can-i-run-co-op-cloud-on-arm)

docs/maintainers/handbook.md

@@ -466,3 +466,67 @@ 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 a member of Autonomic. 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) listing
+- 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).
+
+#### `abra`
+
+`abra` will read labels and store backups in `~/.abra/backups/...`.
+
+#### `backup-bot-two`
+
+Please see the [`README.md`](https://git.coopcloud.tech/coop-cloud/backup-bot-two#backupbot-ii) for the full docs.
+
+### 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.

docs/operators/handbook.md

@@ -310,4 +310,24 @@ Running `server add` with `-d/--debug` should help you debug what is going on un
 
 ## How do I attach to a running container?
 
-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.
+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.
+
+## Can I run Co-op Cloud on ARM?
+
+`@Mayel`:
+
+> FYI I've been running on ARM for a while with no troubles (as long as images
+> used support it of course, `abra` doesn't work yet!) 😀 ... in cases where I
+> couldn't find a multiarch image I simply have eg. image: ${DB_DOCKER_IMAGE}
+> in the docker-compose and set that to a compatible image in the env config
+> ... there was really nothing to it, apart from making sure to use multiarch
+> or arm images
+
+See [`#312`](https://git.coopcloud.tech/coop-cloud/organising/issues/312) for more.
+
+## 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.

requirements.txt

@@ -1,4 +1,4 @@
 mkdocs-awesome-pages-plugin==2.7.0
 mkdocs-material-extensions==1.0.3
-mkdocs-material==8.2.8
+mkdocs-material==8.2.9
 mkdocs==1.3.0