Example of using Apprise with base image.

[ThorpeJosh]

Hi, I know that Apprise was added to the base image a while back. I can't find any examples of how to use it though (in the context of a borgmatic backup via cron).

I am wanting to migrate away from the msmtp image, as I use apprise on a few other projects for email alerts due to being easier to install and setup in a container than msmtp.

How are you guys using it (just piping the output of borgmatic into apprise?) and could the base README be updated to have an example?

@modem7 I know you are spearheading apprise. Thanks!

[ThorpeJosh]

Suggesting maybe an update to ./base/data/borgmatic.d/crontab.txt and the ./base/README.md.

I am happy to make the changes.

[jonathan8devs]

It's pretty simple!
Take the base image and create the folder:

mkdir -p data/scripts

Then you need a file which brings the Apprise configuration (according to the Apprise documentation it would also work via cli - but I prefer this variant):

nano data/scripts/send_notification.py

#!/usr/bin/env python3
import sys
import apprise

# Create an Apprise object
apobj = apprise.Apprise()

# Add notification services (replace the URLs with your own).
apobj.add('slack://token_a/token_b/token_c')
apobj.add('telegram://bot_token/chat_id')

# Send a message to all configured services
title = sys.argv[1]
message = sys.argv[2]
apobj.notify(title=title, body=message)

Now we have to call the script after the backup. For this I create a run.sh like it is the case with msmtp:

nano data/scripts/run.sh

#!/bin/bash

LOGFILE="/tmp/backup_run_$(date +%s).log"

set -o pipefail
/usr/local/bin/borgmatic --stats -v 0 2>&1 | tee $LOGFILE

if [ $? -eq "0" ]; then
    SUBJECT_PREFIX="SUCCESS"
else
    SUBJECT_PREFIX="FAILED"
fi

/scripts/send_notification.py "$SUBJECT_PREFIX: Borgmatic" "$(cat $LOGFILE)"

rm $LOGFILE

Now the crontab.txt must still be adapted:

0 1 * * * /bin/bash /scripts/run.sh 2>&1

Last but not least the docker-compose.yml has to be modified and extended with scripts:

version: '3'
services:
  borgmatic:
    image: ghcr.io/borgmatic-collective/borgmatic
    container_name: borgmatic
    volumes:
      - ${VOLUME_SOURCE}:/mnt/source:ro            # backup source
      - ${VOLUME_TARGET}:/mnt/borg-repository      # backup target
      - ${VOLUME_ETC_BORGMATIC}:/etc/borgmatic.d/  # borgmatic config file(s) + crontab.txt
      - ${VOLUME_BORGMATIC_STATE}:/root/.borgmatic # borgmatic state files
      - ${VOLUME_BORG_CONFIG}:/root/.config/borg   # config and keyfiles
      - ${VOLUME_SSH}:/root/.ssh                   # ssh key for remote repositories
      - ${VOLUME_BORG_CACHE}:/root/.cache/borg     # checksums used for deduplication
      - ./data/scripts:/scripts
    environment:
      - TZ=${TZ}
      - BORG_PASSPHRASE=${BORG_PASSPHRASE}

Of course you can use a variable here but faultiness in this instruction wins :D

[ThorpeJosh]

Wow! Thanks for the write-up and the PR @jonathan8devs

I know you started with "It's pretty simple!" but I can't help thinking this is way more complex than it should be.....

Apprise has a CLI (and it can take the notification body from stdin) so the python doesn't seem necessary.

I raised this issue to create discussion and see how others are using apprise and hopefully get the recommended method added to the docs.

I've actually just been running the following for a bit without issues. It doesn't change the message based on a failure or not, but it can be added with an if-else+subject_prefix like you have. I've been using email and signal alerts with apprise for the last few weeks without issues (Only show email example below).

#!/bin/bash
$MAIL_SUBJECT="Subject Message"
APPRISE_MAIL_URI="mailto://$MAIL_FROM:$MAIL_PASSWORD@gmail.com/$MAIL_TO"

/usr/local/bin/borgmatic --stats -v 0 2>&1 | apprise -vv -t "$MAIL_SUBJECT" "$APPRISE_MAIL_URI"

[modem7]

Sorry I've been afk guys! Been absolutely inundated at work!

@grantbevis - would you be able to take point until I can have a proper look? I don't want to glance over what looks to be an amazing bit of work!

[witten]

Related ticket: https://projects.torsion.org/borgmatic-collective/borgmatic/issues/715

[iljur]

data/scripts/run.sh

Does the "set -o pipefail" really catch the exitcodes of each individual invocation of borg by borgmatic and throw out the highest exitcode overall at the end?

With my installation the create action exits often with rc1/warning (files changed) but $? is "0" after all actions.

Is that expected behaviour?

[witten]

FYI borgmatic now includes native support for Apprise in main. This will be part of the next release: https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook

@grantbevis @modem7

[modem7]

FYI borgmatic now includes native support for Apprise in main. This will be part of the next release: https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook

@grantbevis @modem7

That's great news!

Once my server is back up and running, I'm going to try and migrate docker borgmatic to s6, remove supercronic in favour of the inbuilt cron, and I'll also remove apprise as it'll be included.

That'll definitely slim things up somewhat, and we'll close this ticket once that change goes through.

[ThorpeJosh]

@modem7 @grantbevis

Agreed this is great news.

Just note that apprise won't be installed with borgmatic by default. It is an extras package with no version specified.
setup.py source code

Up to you if you want to still control the apprise package version in the docker image, or install borgmatic with pip install borgmatic[Apprise] and let it grab the latest version.

I would suggest locking the version. I've been involved a bit with the apprise and apprise-api projects recently and I've witnessed changes/releases get pushed through quickly without much testing and the behaviour does not match the documentation. Patch/fix releases are common, up to you how you want to handle this.

[ThorpeJosh]

FYI borgmatic now includes native support for Apprise in main. This will be part of the next release: https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook

I'll close this issue. An example of using Apprise with borgmatic 1.8.4 can be found at the link above.

[jonathan8devs]

I revisited this topic recently as I am also writing for a German blog. The guide there was getting outdated, and I wanted to update it. The simplest way to set up a regular backup with log handling is as follows:

Crontab.txt

*/5 * * * * PATH=$PATH:/usr/local/bin /usr/local/bin/borgmatic --stats -v 0 > /tmp/backup_run.log

Config.yaml

before_backup:
  - echo "Starting a backup job."
after_backup:
  - echo "Backup created."
  - apprise -vv -t "your-subdomain.example.com - BorgBackup" -b "$(cat /tmp/backup_run.log)" "mailtos://smtp.example.com:587?user=info@example.com&pass=YourSecurePassword&from=server@example.com"
on_error:
  - echo "Error while creating a backup."

[ThorpeJosh]

Thanks for sharing @jonathan8devs , that approach is nice and simple. Also makes it easy to send a different notification on_error. A fair bit more concise than my run script.