From a86ac153631715b4ab714f3d707f7ad2a6efed61 Mon Sep 17 00:00:00 2001
From: Moritz <moritz.m@local-it.org>
Date: Thu, 7 Sep 2023 13:44:38 +0200
Subject: [PATCH] README

---
 .env.sample |   2 +-
 README.md   | 106 +++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 94 insertions(+), 14 deletions(-)

diff --git a/.env.sample b/.env.sample
index 8a0ef77..a382dfb 100644
--- a/.env.sample
+++ b/.env.sample
@@ -6,7 +6,7 @@ COMPOSE_FILE=compose.yml
 
 RESTIC_REPO=/backups/restic
 
-CRON_SCHEDULE='*/5 * * * *'
+CRON_SCHEDULE='30 */4 * * *'
 
 # swarm-cronjob, instead of built-in cron
 #COMPOSE_FILE="$COMPOSE_FILE:compose.swarm-cronjob.yml"
diff --git a/README.md b/README.md
index 53b9ea6..025bedf 100644
--- a/README.md
+++ b/README.md
@@ -20,12 +20,12 @@ Backupbot II tries to help, by
 
 ### With Co-op Cloud
 
-1. Set up Docker Swarm and [`abra`][abra]
-2. `abra app new backup-bot-two`
-3. `abra app config <your-app-name>`, and set storage options. Either configure `CRON_SCHEDULE`, or set up `swarm-cronjob`
-4. `abra app secret generate <your-app-name> restic-password v1`, optionally with `--pass` before `<your-app-name>` to save the generated secret in `pass`.
-5. `abra app secret insert <your-app-name> ssh-key v1 ...` or similar, to load required secrets.
-4. `abra app deploy <your-app-name>`
+
+* `abra app new backup-bot-two`
+* `abra app config <app-name>`
+    - set storage options. Either configure `CRON_SCHEDULE`, or set up `swarm-cronjob`
+* `abra app secret generate -a <app_name>`
+* `abra app deploy <app-name>`
 
 <!-- metadata -->
 
@@ -42,6 +42,93 @@ Backupbot II tries to help, by
 
 ## Configuration
 
+Per default Backupbot stores the backups locally in the repository `/backups/restic`, which is accessible as volume at `/var/lib/docker/volumes/<app_name>_backups/_data/restic/`
+
+The backup location can be changed using the `RESTIC_REPO` env variable.
+
+### S3 Storage
+
+To use S3 storage as backup location set the following envs:
+```
+RESTIC_REPO=s3:<S3-SERVICE-URL>/<BUCKET-NAME>
+SECRET_AWS_SECRET_ACCESS_KEY_VERSION=v1
+AWS_ACCESS_KEY_ID=<MY_ACCESS_KEY>
+COMPOSE_FILE="$COMPOSE_FILE:compose.s3.yml"
+```
+and add your `<SECRET_ACCESS_KEY>` as docker secret:
+`abra app secret insert <app_name> aws_secret_access_key v1 <SECRET_ACCESS_KEY>`
+
+See [restic s3 docs](https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#amazon-s3) for more information.
+
+### SFTP Storage
+
+> TODO
+
+To use SFTP storage as backup location set the following envs:
+```
+RESTIC_REPO=sftp:user@host:/restic-repo-path
+SECRET_SSH_KEY_VERSION=v1
+SSH_HOST_KEY="hostname ssh-rsa AAAAB3...
+COMPOSE_FILE="$COMPOSE_FILE:compose.ssh.yml"
+```
+
+Generate an ssh keypair: `ssh-keygen -t ed25519 -f backupkey -P ''`
+and add your `SSH_KEY` as docker secret:
+`abra app secret insert <app_name> ssh_key v1 "$(cat backupkey)"`
+
+
+## Usage
+
+
+Create a backup of all apps:
+
+`abra app run <app_name> app -- backup create`
+
+> The apps to backup up need to be deployed
+
+Create an individual backup:
+
+`abra app run <app_name> app -- backup --host <target_app_name> create`
+
+Create a backup a local repository:
+
+`abra app run <app_name> app -- backup create -r /backups/restic`
+
+> It is recommended to shutdown/undeploy an app before restoring the data
+
+Restore the latest backup of all including apps:
+
+`abra app run <app_name> app -- backup restore`
+
+Restore a specific backup of an individual app:
+
+`abra app run <app_name> app -- backup --host <target_app_name> restore --snapshot <snapshot_id>`
+
+Show all snapshots:
+
+`abra app run <app_name> app -- backup snapshots`
+
+Show all snapshots containing a specific app:
+
+`abra app run <app_name> app -- backup --host <target_app_name> snapshots`
+
+Show all files inside the latest snapshot (can be very verbose):
+
+`abra app run <app_name> app -- backup ls`
+
+Show specific files inside a selected snapshot:
+`abra app run <app_name> app -- backup ls --snapshot <snapshot_id> --path /var/lib/docker/volumes/`
+
+Download files from a snapshot:
+
+```
+filename=$(abra app run <app_name> app -- backup download --snapshot <snapshot_id> --path <absolute_path>)
+abra app cp <app_name> app:$filename .
+```
+
+
+## Recipe Configuration
+
 Like Traefik, or `swarm-cronjob`, Backupbot II uses access to the Docker socket to read labels from running Docker Swarm services:
 
 ```
@@ -60,11 +147,4 @@ services:
 
 As in the above example, you can reference Docker Secrets, e.g. for looking up database passwords, by reading the files in `/run/secrets` directly.
 
-## Development
-
-1. Install `direnv`
-2. `cp .envrc.sample .envrc`
-3. Edit `.envrc` as appropriate, including setting `DOCKER_CONTEXT` to a remote Docker context, if you're not running a swarm server locally.
-4. Run `./backup.sh` -- you can add the `--skip-backup` or `--skip-upload` options if you just want to test one other step
-
 [abra]: https://git.autonomic.zone/autonomic-cooperative/abra