Skip to content

Commit bbce492

Browse files
pablomendezroyopablomendezroyo
committed
add notifications
1 parent c665443 commit bbce492

File tree

4 files changed

+175
-0
lines changed

4 files changed

+175
-0
lines changed

‎docs/dev/cicd.md‎

Whitespace-only changes.

‎docs/dev/notifications.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# 🔔 Package notifications
2+
3+
Notifications are a way to inform users about events that are happening in the dappnode. They are displayed in the [notifications tab](http://dappmanager.dappnode/notifications) in the dappnode UI. Notifications are sent by a third party software "gatus" that monitors the services running in the dappnode or arbitrary services that send notifications. The user will be able to configure the notifications they want to receive as well as the tresholds (if any) for the notifications.
4+
5+
:::info
6+
It is mandatory for users to receive notifications having installed the [Notifications package](https://github.com/dappnode/DNP_NOTIFICATIONS)
7+
:::
8+
9+
**Notifications structure**: each notification has a structure that includes the following fields:
10+
11+
- `title`: The title of the notification. Belongs to notification payload.
12+
- `body`: The body of the notification. Belongs to notification payload.
13+
- `category`: The category of the notification. This is used to group notifications by type. Belongs to notification payload.
14+
- `dnpName`: The DNP name of the package that sent the notification. This is used to identify the package that sent the notification. Belongs to notification payload.
15+
- `seen`: A boolean value that indicates whether the notification has been seen by the user or not. It is handled automatically by the notifications package, setting the default value false. Seen will be set to true once the uer sees the notification.
16+
- `timestamp`: The timestamp of when the notification was sent. This is used to sort notifications by date. It is automatically set by the notifications package when receiving the notification.
17+
- `callToAction`: An optional field that includes a title and a URL. This is used to provide a link to the user to take action on the notification. Belongs to notification payload.
18+
- `title`: The title of the call to action. This is used to provide a title for the link.
19+
- `url`: The URL of the call to action. This is used to provide a link for the user to take action on the notification.
20+
- `errors`: An optional field that includes an error message. This is used to provide additional information about the notification. If provided, the notification will not be shown in the inbox. Belongs to notification payload.
21+
- `icon`: An optional field that includes an icon URL. This is used to provide an icon for the notification. If not provided it will be used the pkg icon that sent the notification. Belongs to notification payload.
22+
23+
```json
24+
{
25+
"title": "string", // e.g "Geth ethereum node sync status"
26+
"body": "string", // e.g "Triggered: Geth ethereum node syncing"
27+
"category": "string", // e.g "ethereum"
28+
"dnpName": "string", // e.g "geth.dnp.dappnode.eth"
29+
"seen": "boolean", // e.g "false"
30+
"timestamp": "string", // e.g "2023-10-01T12:00:00Z"
31+
"callToAction?": {
32+
"title": "string", // e.g "View logs"
33+
"url": "string" // e.g "http://dappmanager.dappnode/packages/my/geth.dnpo.dappnode.eth/logs"
34+
},
35+
"errors?": "string", // e.g "Error: no such host: geth.dappnode"
36+
"icon?": "string" // e.g "https://gateway.ipfs.dappnode.io/ipfs/QmTVc5LQkTuaN3VxcteQ2E27pHSVJakE6XPo2FMxQTP284"
37+
}
38+
```
39+
40+
**Notifications package API**: The notifications package exposes an API that allows other packages to send notifications. The API is a simple HTTP POST request that includes the notification structure as the body of the request. The API is available at the following URL: `http://notifier.notifications.dappnode:8080/api/v1/notifications`.
41+
42+
```bash
43+
curl -X POST \
44+
http://notifier.notifications.dappnode:8080/api/v1/notifications \
45+
-H 'Content-Type: application/json' \
46+
-d '{
47+
"title": "Test notification",
48+
"body": "This is a test notification sent with curl",
49+
"category": "other",
50+
"dnpName": "test.dnp.dappnode.eth",
51+
"callToAction": {
52+
"title": "Hello world",
53+
"url": "http://dappmanager.dappnode"
54+
},
55+
"icon": "https://gateway.ipfs.dappnode.io/ipfs/QmTVc5LQkTuaN3VxcteQ2E27pHSVJakE6XPo2FMxQTP284"
56+
}'
57+
```
58+
59+
## Notifications Inbox
60+
61+
The notifications inbox is a place where users can see all the notifications that have been sent to them. The notifications are grouped by category and can be filtered by date, dnpName and category. Users can also mark notifications as read or delete them.
62+
63+
<p align="center">
64+
<img src="/img/notifications-inbox.png" alt="unsub-initial-dialog" width="400"/>
65+
</p>
66+
67+
## Notifications Settings
68+
69+
The notifications settings are a place where users can configure the notifications they want to receive. Users can enable or disable notifications for each category and set the thresholds for each notification. The thresholds are used to determine when a notification should be sent. For example, if a user wants to receive a notification when the CPU usage is above 80%, they can set the threshold to 80%. If the CPU usage is above 80%, a notification will be sent.
70+
71+
<p align="center">
72+
<img src="/img/notifications-settings.png" alt="unsub-initial-dialog" width="400"/>
73+
</p>
74+
75+
## Gatus endpoints
76+
77+
The most common and easiest way to configure notifications in dappnode is using the [gatus](https://github.com/TwiN/gatus) standard. To configure notifications using gatus, you need to create a `*notifications.yaml` file. This file must follow the standard defined in the [gatus - notifications file reference]().
78+
79+
Gatus will take care of monitoring the endpoint you defined, automatically triggering the alert with the desired notification payload. Furhtermore you can benefit from some of the gatus features, such as:
80+
81+
- `interval`: The interval at which the endpoint will be monitored. This is used to determine how often the endpoint will be checked.
82+
- `failure-threshold`: The number of consecutive failures before the alert is triggered. This is used to determine how many times the endpoint must fail before a notification is sent.
83+
- `success-threshold`: The number of consecutive successes before the alert is resolved. This is used to determine how many times the endpoint must succeed before the notification is resolved.
84+
- `send-on-resolved`: If set to true, a notification will be sent when the alert is resolved. This is used to inform the user when the issue has been resolved.
85+
86+
**Example**
87+
88+
```yaml
89+
endpoints:
90+
- name: "Mainnet ETH Node Syncing Check" # Notification title
91+
enabled: true
92+
group: "ethereum" # Notification category
93+
url: "http://geth.dappnode:8545" # Notification dnpName
94+
method: "POST"
95+
body: |
96+
{"jsonrpc": "2.0", "id": 1, "method": "eth_syncing", "params": []}
97+
headers:
98+
Content-Type: "application/json"
99+
interval: "30s"
100+
conditions:
101+
- "[BODY].result == false"
102+
definition:
103+
title: "Mainnet ETH Node Synced Check" # Notifications - settings: title of the notification to be configured
104+
description: "Check if the Mainnet ETH Node is synced. You will receive a notification if the node is syncing and another one when it is synced." # Notifications - settings: description of the notification to be configured
105+
alerts:
106+
- type: custom
107+
enabled: true
108+
description: "Geth Ethereum Node syncing" # Notification description
109+
failure-threshold: 2
110+
success-threshold: 1
111+
send-on-resolved: true
112+
```
113+
114+
In the example from above:
115+
116+
- Notification payload:
117+
- Name: will be used as the title of the notification.
118+
- Alerts - description: will be used as the body of the notification.
119+
- Group: will be used as the category of the notification.
120+
- URL: will be used as the dnpName of the notification. The dnpName will be inferred from the URL.
121+
- Notification settings:
122+
- Title: will be used as the title of the notification in the notifications settings.
123+
- Description: will be used as the description of the notification in the notifications settings.
124+
125+
:::info
126+
[Gatus](https://github.com/TwiN/gatus) is a third party software that monitors the services defined in a config file. It can be configured to trigger automatic alerting based on needs.
127+
:::
128+
129+
## Custom endpoints
130+
131+
There might be some cases where Gatus has some limitations and your notification requires some custom logic. In this case, you can create a custom endpoint that will be triggered by Gatus. This endpoint will be responsible for sending the notification to the notifications package.
132+
133+
When using custom endpoints, you need to retrieve the user settings from the dappmanager API:
134+
135+
```bash
136+
curl -X GET \
137+
http://dappmanager.dappnode/package-manifest/dms.dnp.dappnode.eth \
138+
-H 'Content-Type: application/json'
139+
```
140+
141+
You will receive the manifest as a response from the server. Within this manifest you can get the notifications user settings for the custom endpoints:
142+
143+
```json
144+
{
145+
"notifications": {
146+
"customEndpoints": [
147+
{
148+
"name": "string", // e.g "Package updates notifications"
149+
"description": "string", // e.g "Receive package updates notifications when a new version is available."
150+
"enabled": true // e.g true
151+
}
152+
]
153+
}
154+
}
155+
```
156+
157+
From the example above, you can see that the user has enabled the custom endpoint for such notifications. You can use this information to trigger the notification.
158+
159+
**Example**
160+
161+
```yaml
162+
customEndpoints:
163+
- name: "Package updates notifications"
164+
description: "Receive package updates notifications when a new version is available."
165+
enabled: true
166+
```
167+
168+
## Communication channels
169+
170+
As for now there are only the UI communication channel with the user.
171+
172+
There are plans to implement more communications channels, probably with the following priorities:
173+
174+
- Web push notifications
175+
- Telegram

‎static/img/notifications-inbox.png‎

256 KB
Loading

‎static/img/notifications-settings.png‎

319 KB
Loading

0 commit comments

Comments
 (0)