diff --git a/docs/behavior/notifications-behavior.mdx b/docs/behavior/notifications-behavior.mdx new file mode 100644 index 0000000..28e69e2 --- /dev/null +++ b/docs/behavior/notifications-behavior.mdx @@ -0,0 +1,57 @@ +--- +id: notifications +title: Notifications +--- + +Recyclarr integrates with [Apprise API][apprise], a versatile notification platform, to offer robust +notification capabilities. This integration allows Recyclarr to send notifications to a wide array +of services, including popular platforms like Discord and Email. For a comprehensive list of +supported notification targets, please refer to the [Apprise documentation][urls]. + +This page provides an overview of Recyclarr's notification system, explaining its behavior and the +information it provides. Notifications in Recyclarr are designed to keep you informed about sync +operations, providing real-time updates on the process and detailed information about the results. + +[apprise]: https://github.com/caronc/apprise-api +[urls]: https://github.com/caronc/apprise/wiki#notification-services + +## Setting Up Notifications + +To configure notifications for Recyclarr, you'll need to modify your `settings.yml` file. For +detailed instructions on how to set up notifications, including examples and all available options, +please refer to the [notification settings reference][settings] page. + +[settings]: /yaml/settings-reference/notifications.mdx + +## Notification Behavior + +Currently, Recyclarr's notification system is focused on [sync operations][sync]. Notifications are +designed to be comprehensive, providing a complete overview of the operation without overwhelming +you with too many messages. Here are some key points to understand about the notification behavior: + +- **Single Notification per Sync**: Recyclarr sends one consolidated notification for each `sync` + command execution, regardless of the number of service instances configured in your YAML file. + +- **Multi-Service Support**: If you have multiple service instances configured (e.g., 2 Radarr and 1 + Sonarr), the single notification will include information about the sync operation for all + services. + +- **Timing**: The notification is sent upon completion of the entire sync operation across all + configured services. + +[sync]: /cli/sync.mdx + +## Notification Content + +The notification sent after each sync operation includes the following information: + +- **Overall Status**: An indication of whether the sync operation was successful or if it failed. + +- **Service-Specific Statistics**: For each service instance synced (e.g., Radarr, Sonarr), you'll + receive high-level statistical information, such as: + - Number of custom formats synced + - How many quality profiles were updated + - Other relevant metrics specific to the service + +- **Error and Warning Reports**: Any errors or warnings that occurred during the sync operation are + included in the notification. diff --git a/docs/yaml/settings-reference/notifications.mdx b/docs/yaml/settings-reference/notifications.mdx new file mode 100644 index 0000000..28b2bb0 --- /dev/null +++ b/docs/yaml/settings-reference/notifications.mdx @@ -0,0 +1,80 @@ +--- +id: notifications +title: Notifications +--- + +This page covers two different ways to configure Apprise notifications in Recyclarr: Stateless Mode +and Stateful Mode. + +:::caution + +Details regarding how to use and configure Apprise itself is outside of the scope of this wiki page +and, in particular, Recyclarr support channels. Apprise-specific questions should be directed to the +appropriate Apprise support channels. + +::: + +## Stateful Mode + +When using [stateful mode], the details of which specific URLs to publish notifications to is +controlled by Apprise API configuration. + +[stateful mode]: https://github.com/caronc/apprise-api#persistent-stateful-storage-solution + +```yml +notifications: + apprise: + mode: stateful + base_url: http://localhost:8000 + key: recyclarr + tags: foo bar, baz +``` + +Reference for the `apprise` section is below. Note that most of these values are forwarded directly +to Apprise API and you should rely on their documentation for more information. + +- `mode` *(Required)*
+ Set this to `stateful` to enable stateful mode. + +- `base_url` *(Required)*
+ This is the base URL of the Apprise API server that Recyclarr should send notifications to. + +- `key` *(Required)*
+ The key represents a configuration file on the Apprise API server that will be used to determine + where notifications are sent. + +- `tags` *(Optional)*
+ Optionally notify only those URLs tagged accordingly. Use a comma (`,`) to `OR` your tags and a + space (` `) to `AND` them. + +## Stateless Mode + +Use [stateless mode] when you want to sidecar the Apprise API without it having access to storage. +This means that Recyclarr's notification settings will contain the list of URLs to publish +notifications to. + +[stateless mode]: https://github.com/caronc/apprise-api#stateless-mode + +```yml +notifications: + apprise: + mode: stateless + base_url: http://localhost:8000 + urls: + - https://discord.com/api/webhooks/secret +``` + +Reference for the `apprise` section is below. Note that most of these values are forwarded directly +to Apprise API and you should rely on their documentation for more information. + +- `mode` *(Required)*
+ Set this to `stateless` to enable stateless mode. + +- `base_url` *(Required)*
+ This is the base URL of the Apprise API server that Recyclarr should send notifications to. + +- `urls` *(Required)*
+ One or more URLs that apprise will forward notifications to. If you want to know what kind of URLs + to put here, please visit the [Apprise API documentation][urls]. + +[urls]: https://github.com/caronc/apprise/wiki#notification-services