Merge pull request #277 from Psycho0verload/docu/basic_apprise

[Docu] Documentation for Apprise - Supports Pre-1.8.4 and 1.8.4+

README.md

@@ -91,6 +91,103 @@ You also have the option to use Docker Secrets for more sensitive information. T
 
 For every environment variable like `BORG_PASSPHRASE`, you can create a corresponding secret file, named as `BORG_PASSPHRASE_FILE`. Place the content of the secret inside this file. The startup script will automatically look for corresponding `_FILE` secrets if the environment variables are not set and load them.
 
+## Using Apprise for Notifications
+
+To enhance your experience with Borgmatic, we'll show you a quick example of how to use Apprise for notifications. Apprise is a versatile tool that integrates with a variety of services and is built into Borgmatic. With the upcoming version 1.8.4 also natively. Here's a quick example of how you can use Apprise.
+
+### Basic Setup
+
+#### Cronjob Configuration
+
+In an unmodified Borgmatic installation, your `cronjob.txt` might look something like this:
+
+```
+0 1 * * * PATH=$PATH:/usr/local/bin /usr/local/bin/borgmatic --stats -v 0 2>&1
+```
+
+To incorporate Apprise notifications, you can modify it like this:
+
+```
+*/5 * * * * PATH=$PATH:/usr/local/bin /usr/local/bin/borgmatic --stats -v 0 > /tmp/backup_run.log
+```
+
+#### Borgmatic Configuration
+
+Add the following lines to your Borgmatic configuration file (`config.yaml`):
+
+```yaml
+before_backup:
+  - echo "Starting a backup job."
+
+after_backup:
+  - echo "Backup created."
+  - apprise -vv -t "✅ SUCCESS" -b "$(cat /tmp/backup_run.log)" "mailtos://smtp.example.com:[email protected]&pass=YourSecurePassword&[email protected]"
+
+on_error:
+  - echo "Error while creating a backup."
+  - apprise -vv -t "❌ FAILED" -b "$(cat /tmp/backup_run.log)" "mailtos://smtp.example.com:[email protected]&pass=YourSecurePassword&[email protected]"
+```
+
+##### Note:
+
+If you don't want to send the log file, you can replace `-b "$(cat /tmp/backup_run.log)"` with a custom message like `-b "My message"`.
+
+### Advanced Options
+
+##### Apprise Capabilities
+
+Apprise offers a variety of services to send notifications to, such as Telegram, Slack, Discord, and many more. For a complete list, visit the [Apprise GitHub page](https://github.com/caronc/apprise#productivity-based-notifications).
+
+#### Example for Multiple Services
+
+Apprise allows you to notify multiple services at the same time:
+
+```yaml
+after_backup:
+  - echo "Backup created."
+  - apprise -vv -t "✅ SUCCESS" -b "$(cat /tmp/backup_run.log)" "mailto://smtp.example.com:[email protected]&pass=YourSecurePassword&[email protected],slack://token@Txxxx/Bxxxx/Cxxxx"
+```
+
+### Native Apprise Configuration in Borgmatic 1.8.4+
+
+Starting from version 1.8.4, Borgmatic has native support for Apprise within its configuration. This makes it even easier to set up notifications. Below is how you can add Apprise directly to your Borgmatic `config.yaml`.
+
+```yaml
+apprise:
+    services:
+        - url: mailto://smtp.example.com:[email protected]&pass=YourSecurePassword&[email protected]
+          label: mail
+        - url: slack://token@Txxxx/Bxxxx/Cxxxx
+          label: slack
+
+    start:
+        title: ⚙️ Started
+        body: Starting backup process.
+
+    finish:
+        title: ✅ SUCCESS
+        body: Backups successfully made.
+
+    fail:
+        title: ❌ FAILED
+        body: Your backups have failed.
+```
+
+#### Important Note
+
+Just like in the previous configuration, you can use `$(cat /tmp/backup_run.log)` to send log outputs as part of the notification body. Simply replace the `body` value with this variable to include the log in your notifications.
+
+```yaml
+    finish:
+        title: ✅ SUCCESS
+        body: $(cat /tmp/backup_run.log)
+```
+
+### Conclusion
+
+Apprise provides a flexible and powerful way to handle notifications in Borgmatic. Be sure to check out the [official Apprise documentation](https://github.com/caronc/apprise#productivity-based-notifications) for a full range of options and capabilities.
+
+
 ## Other usage methods
 
 ### Run borgmatic like a binary through a container