diff --git a/Dockerfile b/Dockerfile index bacfda2..cb93467 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM squidfunk/mkdocs-material:8.2.8 +FROM squidfunk/mkdocs-material:8.2.9 EXPOSE 8000 diff --git a/docs/abra/upgrade.md b/docs/abra/upgrade.md index 266628e..ef7e0b1 100644 --- a/docs/abra/upgrade.md +++ b/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. diff --git a/docs/intro/contact.md b/docs/intro/contact.md index e9adf25..769b4af 100644 --- a/docs/intro/contact.md +++ b/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 diff --git a/docs/intro/faq.md b/docs/intro/faq.md index b115c34..2fc8748 100644 --- a/docs/intro/faq.md +++ b/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) diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md index cc5ffbd..dcbf896 100644 --- a/docs/maintainers/handbook.md +++ b/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 -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. diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md index 22b9090..1892c49 100644 --- a/docs/operators/handbook.md +++ b/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 `. For example, you could run `abra app run cloud.lumbung.space app bash` to open a new bash terminal session inside your remote container. \ No newline at end of file +If you need to run a command within a running container you can use `abra app run `. 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. diff --git a/requirements.txt b/requirements.txt index aaf5f70..9142f7e 100644 --- a/requirements.txt +++ b/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