From 0d47001c9dfb6f70fb9f76f779b4dc447169410a Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Tue, 19 Apr 2022 13:41:21 +0200
Subject: [PATCH] backup & restore docs

---
 docs/maintainers/handbook.md | 41 ++++++++++++++++++++++++++++++++++++
 docs/operators/handbook.md   |  7 ++++++
 2 files changed, 48 insertions(+)

diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md
index 29193da..dcbf896 100644
--- a/docs/maintainers/handbook.md
+++ b/docs/maintainers/handbook.md
@@ -489,3 +489,44 @@ 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 abb84e3..1892c49 100644
--- a/docs/operators/handbook.md
+++ b/docs/operators/handbook.md
@@ -324,3 +324,10 @@ 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.