reviewed and corrected

README.md

@@ -6,53 +6,62 @@ Container image for creating cron-scheduled backups with [borg backup](https://w
   - Fast backup runs and pruning of old backups.
   - Encryption to allow backup storage in insecure offsite-locations.
   - FUSE mount support for easy recovery.
-  - Focus on local backups. For cloud backups [restic](https://restic.net/) offers as alternative more options.
+  - Focus on local backups. For cloud backups [restic](https://restic.net/) might be an alternative.
 
 ## Installation & Setup
-  1. Build:
-    - Run `docker compose build` to build the container image from `./build/Dockerfile`
-  2. Configuration:
-    - `cp` [.env.template](.env.template) `.env `
-    - Adapt `.env`, parameters are explained in the template file
-  3. Init the backup archive:
+  0. Clone this repository
+  1. Build the container image from [./build/Dockerfile](./build/Dockerfile):
+    - `docker compose build`
+  2. Configure backup in `.env`. Copy and adapt [.env.template](.env.template) which describes all variables:  
+     - `cp .env.template .env && vi .env`
+  3. Borg needs an initial init of the backup archive. To create an encrypted archive run:
     - `docker exec --rm -it borg bash -c "borg init --encryption repokey-blake2"`
-  4. Start the container:
+  4. Finally, start the container and wait for cron to start the backup:
     - `docker compose up -d`
-  5. Upgrade:
+  5. (Optional) Run an unscheduled backup:
+    - `docker exec borg bash -c 'do-backup.sh'`
+  6. Upgrade:
     - Alpine and Borg versions are hard-coded in `docker-compose.yml`.
-    - [Borg Release Notes](https://github.com/borgbackup/borg/releases) should be consulted prior to upgrades.
+    - [Borg Release Notes](https://github.com/borgbackup/borg/releases) should be consulted for breaking changes.
 
 ## Preparation for disaster recovery 
-Very important! Following files MUST be stored along with the backup to enable decryption of the backup data:
-  - `.env`-file file containing the passphrase
-  - Keyfiles, stored in ./data/.config/borg/keys/
+Very IMPORTANT! Following files MUST be stored along with the backup to enable decryption of the backup data:
+  - `.env`-file containing the passphrase
+  - Keyfile(s), stored in ./data/.config/borg/keys/
   
 ## Backup restore
-  1. Stop the backup container: `docker compose down`
-  2. Run an interactive shell in the recovery: `docker compose -f docker-compose.yml -f docker-compose.restore.yml run borg bash`
-  3. Fuse-mount the backup: `borg mount $BORG_REPO <mount_point>`
+  1. Stop the backup container
+     - `docker compose down`
+  2. Run the container with FUSE-support and enter an interactive shell:
+    - `docker compose -f docker-compose.yml -f docker-compose.restore.yml run borg bash`
+  3. Fuse-mount the backup:
+     - `borg mount $BORG_REPO <mount_point>`
   4. Restore your files
-  5. Unmount and exit: `borg umount <mount_point> && exit`.
-  6. Start the backup container: `docker-compose up -d`
+  5. Unmount and exit:
+     - `borg umount <mount_point> && exit`.
+  6. Start the backup container again:
+     - `docker-compose up -d`
 
 ## Monitoring
-Status and statistics are sent to Prometheus Push-Gateway using a simple bash-script and curl
+Simple bash [scripts](scripts/) sent the backup status and statistics using `curl` to a Prometheus [Pushgateway](https://prometheus.io/docs/practices/pushing/) defined in `.env`.
 
 ## Security considerations
-  - This container will run with root priveliges in order to access all data for backup.
+  - This container runs with root priveliges to allow backup of all data independant of permissions.
   - The backup source-volume is mounted read-only to avoid alering data by mistake.
   - This image has a reduced feature set for sake of simplicity.
-    - [borgmatic](https://torsion.org/borgmatic/) offers more features such as notifications and backup of databases.
+    - If neccessary, [borgmatic](https://torsion.org/borgmatic/) offers more features such as notifications and backup of databases.
     - py3-llfuse and bash are included for comfort during backup restore and could be potentially removed
 	- curl is included to push Promethous metrics and could be removed if this functionality is not used
 
 ## Progam flow
+  - [docker-compose.yml](docker-compose.yml) sets variables `.env` as environment variables in the container
   - `/scripts/entry.sh` is called during container startup
-    and installs the cronjob defined in `.env` variable $CRON
+    and installs the cronjob defined in the $CRON
   - crond starts `/scripts/do-backup.sh` which
-    - notifies Prometheus about the backup status and stats
-	- executes borg backup
+	- executes borg backup 
 	- prunes and compacts old backups
+    - notifies Prometheus about the backup start/stop/fail and stats
 
 # Failure handling
-  - In case Borg fails to create/acquire a lock: `borg break-lock /mnt/repository`
+  - Break lock in case Borg has been interrupted and fails to create/acquire a new lock:
+    - `docker exec borg bash -c 'borg break-lock'`