Apprise

Posted on March 15, 2023  •  6 minutes  • 1086 words  • Other languages:  Français

The v1.3 version of BorgWarehouse included an expected feature : email notifications. This option allows you to be alerted by email if one of your BorgBackup repositories hasn’t been backup for a configurable time. If you don’t have this version yet, I invite you to update your BorgWarehouse instance and set your SMTP settings.

Today, everybody has a mailbox and decentralization¹ of email coupled with the interoperability of this protocol proves wrong, year after year, all those who announced its death. However, email notifications are good, but in 2023 they are not enough. We all have personal and different uses of our email addresses. So, some people don’t prefer to see “alerts” of all kinds filling their mailboxes anymore and use other channels for this kind of notification: SMS, Discord, Slack, Matrix, Mattermost… But how to integrate so many communication channels in one application ?

Following a suggestion from a BorgWarehouse user, I discovered Apprise, the library which is the subject of this new article and which solves this last question.

What is Apprise ?

Apprise is a library written in Python that allows you to send push notifications to almost all the services that exist today. To date, Apprise allows you to notify more than 90 services in version 1.3.0, you can find the exhaustive list here.

For me, the list of advantages of using Apprise is this:

• It’s free software.
• Only one library to manage to communicate with 90+ services.
• Clear and precise documentation for each of the supported services !
• Extremely light.
• Use as a local package or by API with a micro-service deployment.
• Fast and asynchronous sending of notifications to all services.

In my case, for BorgWarehouse, without Apprise I would have had to integrate one by one each notification service desired by the users. This is a laborious task and results in heavy and endless maintenance. With Apprise, users can notify their favorite application in a few clicks !

Last but not least, Apprise is an active project, with many contributors and new services that are regularly integrated.

Python package

You can choose to install Apprise as a local package on your machine. The library is written in Python, so the installation will be done through the Python package manager: pip.

1

pip install apprise

Then, the package allows you to send notifications to any application through a simple command line that can take various options such as:

• The message body
• A title (useful for email notifications)
• The URL of the service to notify

You will find the URL templates for each service in this documentation.

Some examples from the Apprise documentation :

1
2
3
4
5
6

# Send a notification to as many servers as you want
# as you can easily chain one after another (the -vv provides some
# additional verbosity to help let you know what is going on):
apprise -vv -t 'my title' -b 'my notification body' \
   'mailto://myemail:mypass@gmail.com' \
   'pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b'

If you don’t specify a body (-b), then the standard output is used, very useful for sending the result of a command.

1
2
3
4
5
6
7
8

# If you don't specify a --body (-b) then stdin is used allowing
# you to use the tool as part of your every day administration:
cat /proc/cpuinfo | apprise -vv -t 'cpu info' \
   'mailto://myemail:mypass@gmail.com'

# The title field is totally optional
uptime | apprise -vv \
   'discord:///4174216298/JHMHI8qBe7bk2ZwO5U711o3dV_js'

Finally, you can make your life easier and avoid putting your credentials in commands by using Apprise configuration files.

Apprise API

Another way to use Apprise is to deploy it as a microservice via a Docker container for example. The creator of Apprise, Chris Caron, actually provides a docker-compose file in the repository that relates to the Apprise API, here.

However, if you don’t want to build your own Docker image, Chris Caron maintains one available on the dockerhub.

Once your Apprise API server is in place, you can send it API requests and it will take care of sending notifications to the services you set up.

The Apprise API has two main operating modes :

• Stateless
• Persistent storage

For this last mode, it will be useful to save a configuration or a set of learned URLs that you will be able to associate with a {KEY}. The configuration is persistent, you will be able to do it entirely via a web interface and then exploit it via API calls. The possibilities are really big !

Apprise integration in BorgWarehouse

I’m passionate about coding, but learning and understanding how a service like Apprise works and then thinking about how to integrate it in the right way into BorgWarehouse has been equally exciting. So after spending some time reading Apprise’s documentation and testing the library, I set out to figure out how to integrate Apprise the right way into BorgWarehouse so that the user experience would be the best.

For the integration of service URLs, I chose to use a form with a textarea allowing the user to enter as many URLs as they want. To help him build his personal URLs, I provided a link to the Apprise documentation.

Finally, I decided to support both the “Package” mode if the user decides to use Apprise via the Python package, but also the “API Stateless” mode if the user prefers using a Docker container.

Of course, a notification test button was required so that the user could validate his settings.

Conclusion

I have presented you a large part of Apprise, how it works and my use case with BorgWarehouse. Of course, this software allows many other uses and I let you explore the README to fully understand the potential of this incredible library.

I especially thank Chris Caron for this library and his work as well as the whole community of contributors around this nice project that allows to improve the BorgWarehouse experience.