Skip to content

Commit 5dadcdf

Browse files
pablomendezroyopablomendezroyo
authored
[WIP] Add notifications, dns and metrics sections to dev documentation (#470)
* Improve dev documentation * Add metrics * Add dns * add dns * fix grammar issues * add notifications * add notifications file reference * fix link * Fix mateu comments * update link * add comming soon
1 parent f5dd206 commit 5dadcdf

File tree

8 files changed

+439
-0
lines changed

8 files changed

+439
-0
lines changed

‎docs/dev/dns.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# 🌐 DNS
2+
3+
By default, every DAppNode package runs on the Docker network `dncore_network` and uses the default Docker DNS server for name resolution. During installation, the package is assigned a unique domain name (apart from the ones set by default by Docker: container name, service name, etc.) that can be used to access the services running inside the package. This document provides a comprehensive guide on how to access services running inside a package using the assigned domain name.
4+
5+
## Multiservice packages
6+
7+
In multiservice packages, the naming convention is: `<serviceName>.<shortDnpName>.dappnode`, where `serviceName` is the name of the service running inside the package and `shortDnpName` is the name of the package. For example, if you have a package named `my-package` running a service named `my-service`, the domain name to access the service would be `my-service.my-package.dappnode`.
8+
9+
:::info
10+
The short DNP name is derived from the first part of the DNP name, which corresponds to the package name. For example, if the DNP name is `my-package.dnp.dappnode.eth`, the short DNP name would be `my-package`.
11+
:::
12+
13+
**Example multiservice:** [Prysm](https://github.com/dappnode/DAppNodePackage-prysm-generic)
14+
15+
- DNP name: `prysm.dnp.dappnode.eth`
16+
- Docker Compose
17+
18+
```yaml
19+
version: "3.5"
20+
services:
21+
beacon-chain:
22+
build:
23+
context: beacon-chain
24+
args:
25+
volumes:
26+
- beacon-chain-data:/data
27+
restart: unless-stopped
28+
environment:
29+
validator:
30+
build:
31+
context: validator
32+
args:
33+
restart: on-failure
34+
environment:
35+
volumes:
36+
beacon-chain-data: {}
37+
validator-data: {}
38+
```
39+
40+
Aliases will be:
41+
42+
- beacon-chain service: `beacon-chain.prysm.dnp.dappnode`
43+
- validator service: `validator.prysm.dnp.dappnode`
44+
45+
:::tip
46+
A main service can be defined in a multiservice package. This service will be the one used to access the package. For example, if you have a package named `my-package` running a service named `my-service` and you want to access the package using the domain name `my-package.dappnode`, you can define the service `my-service` as the main service. See [manifest file reference - mainService](https://docs.dappnode.io/docs/dev/references/manifest#mainservice) for details on how to define the main service.
47+
:::
48+
49+
## Monoservice packages
50+
51+
In monoservice packages, the domain name is the same as the package name. For example, if you have a package named `my-package`, the domain name to access the service would be `my-package.dappnode`. It also follows the same convention as the multiservice packages. For example, if you have a package named `my-package` running only one service named `my-service`, the domain name to access the service would be `my-service.my-package.dappnode` or `my-package.dappnode`.
52+
53+
**Example monoservice:** [Geth](https://github.com/dappnode/DAppNodePackage-geth-generic)
54+
55+
- DNP name: `geth.dnp.dappnode.eth`
56+
- Docker Compose
57+
58+
```yaml
59+
version: "3.5"
60+
services:
61+
geth:
62+
build:
63+
context: geth
64+
args:
65+
environment:
66+
restart: unless-stopped
67+
```
68+
69+
Alias will be:
70+
71+
- geth service: `geth.dnp.dappnode` and `geth.dnp.dappnode.eth`
72+
73+
## Staker packages - fullnode
74+
75+
Staker packages are a special case in DAppNode. They follow the same DNS conventions mentioned above, with some additional features:
76+
77+
- **EVMs dedicated Docker networks**: Each EVM network supported in DAppNode has a dedicated Docker network that is used by the staker packages to communicate with each other. The Docker network name follows the convention `<network>_network`, e.g., `hoodi_network` for the Hoodi network or `mainnet_network` for the Mainnet network.
78+
- **Fullnode aliases**: The selected Execution and Consensus client has an extra domain name to indicate that it is the client selected by the user. This domain name can be used by other packages to query the RPC node, the validator API, the beacon chain API, etc. (in some cases, it might require authentication). The naming convention is:
79+
- Execution: `execution.<network>.dncore.dappnode`, e.g., `execution.mainnet.dncore.dappnode`
80+
- Consensus:
81+
- Beacon-chain: `beacon-chain.<network>.dncore.dappnode`, e.g., `beacon-chain.mainnet.dncore.dappnode`
82+
- Validator: `validator.<network>.dncore.dappnode`, e.g., `validator.mainnet.dncore.dappnode`
83+
84+
:::info
85+
The fullnode alias is added to both Docker networks, `dncore_network` and `<network>_network`, so it can be accessed from any package running in the DAppNode.
86+
:::

‎docs/dev/metrics.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# 📊 Package Metrics
2+
3+
DAppNode supports an integrated metrics framework based on [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/), powered by the [DMS package](https://docs.dappnode.io/docs/user/packages/dms/).
4+
5+
This framework enables package developers to expose useful metrics and provide prebuilt dashboards to monitor their services.
6+
7+
:::tip
8+
🧠 What is DMS?
9+
The DMS (DAppNode Monitoring Stack) package collects metrics using Prometheus and visualizes them through Grafana. It automatically discovers and injects metrics configurations from installed packages.
10+
:::
11+
12+
## ⚙️ How It Works
13+
14+
To use the metrics framework in your package:
15+
16+
1. The DMS package must be installed by the user.
17+
2. Your package must include:
18+
19+
- One or more Grafana dashboard files
20+
- A Prometheus targets file
21+
22+
## 🧱 File Structure & Naming Convention
23+
24+
These files must follow specific naming conventions and formats:
25+
26+
- **Grafana dashboard files**:
27+
- Name: Must follow this naming pattern `/.*grafana-dashboard.json$/` and be placed in the root directory of your package (or within the variant directory).
28+
- Max size: 10MB
29+
- Multiple files: You can include multiple dashboard files, and they will be merged into a single dashboard in Grafana.
30+
- **Prometheus targets file**:
31+
- Name: Must follow this naming pattern `/.*prometheus-targets.(json|yaml|yml)$/` and be placed in the root directory of your package (or within the variant directory).
32+
- Max size: 1MB
33+
- Only one file: You can only include one targets file.
34+
35+
:::tip
36+
💡 Need the DNS name of a service to configure Prometheus targets?
37+
Refer to the [Package DNS documentation](https://docs.dappnode.io/docs/dev/dns) to learn how to reference services within your Prometheus targets.
38+
:::
39+
40+
## 📦 Single vs Multi-Variant Package Configuration
41+
42+
**Single Variant**
43+
For packages with a single variant:
44+
45+
- Place 1 Prometheus targets file in the root of the package.
46+
- Add as many Grafana dashboard files as needed in the same root directory.
47+
48+
**Multi-Variant**
49+
For multi-variant packages:
50+
51+
- Place Grafana dashboard files in the root of the package, as they are usually shared. See [example](https://github.com/dappnode/DAppNodePackage-geth-generic/blob/main/geth-grafana-dashboard.json).
52+
53+
:::tip
54+
📁 Example:
55+
geth-grafana-dashboard.json
56+
:::
57+
58+
- Place Prometheus targets files in each variant directory, as the data source may differ per variant. See [example](https://github.com/dappnode/DAppNodePackage-geth-generic/blob/main/package_variants/mainnet/prometheus-targets.json).
59+
60+
:::tip
61+
📁 Example:
62+
mainnet/prometheus-targets.json
63+
:::
64+
65+
## 📊 Default Dashboards
66+
67+
The DMS package includes default dashboards and Prometheus targets for [cadvisor](https://github.com/google/cadvisor) and [node_exporter](https://github.com/prometheus/node_exporter). These dashboards provide metrics about the host and Docker containers running on the host.
68+
69+
- [Host dashboards](http://dms.dappnode/d/dms-host/host?orgId=1&refresh=10s)
70+
- [Docker dashboards](http://dms.dappnode/d/dms-docker/docker?orgId=1&refresh=2h)
71+
72+
## 🔗 Useful Links
73+
74+
- Grafana: Access Grafana dashboards, create new ones, and more. **http://dms.dappnode/dashboards**
75+
- Prometheus: Access the Prometheus UI to check target statuses, perform manual queries, and more. **http://prometheus.dms.dappnode:9090/**
76+
- Manager status: Debug which dashboards and targets have been uploaded successfully. **http://manager.dms.dappnode/**

‎docs/dev/notifications.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# 🔔 Package Notifications (Comming soon)
2+
3+
Notifications are a way to inform users about events happening in the DAppNode. They are displayed in the [notifications tab](http://dappmanager.dappnode/notifications) within the DAppNode UI. Notifications are sent by third-party software, "Gatus," which monitors the services running in the DAppNode or arbitrary services that send notifications. Users can configure the notifications they want to receive and set thresholds (if applicable) for these notifications.
4+
5+
:::info
6+
It is mandatory for users to install the [Notifications package](https://github.com/dappnode/DNP_NOTIFICATIONS) to receive notifications.
7+
:::
8+
9+
---
10+
11+
## **Notification Structure**
12+
13+
Each notification has a structure that includes the following fields:
14+
15+
- `title`: The title of the notification. Part of the notification payload.
16+
- `body`: The body of the notification. Part of the notification payload.
17+
- `category`: The category of the notification, used to group notifications by type. Part of the notification payload.
18+
- `dnpName`: The DNP name of the package that sent the notification, used to identify the source package. Part of the notification payload.
19+
- `seen`: A boolean value indicating whether the notification has been seen by the user. This is handled automatically by the notifications package, with a default value of `false`. It is set to `true` once the user views the notification.
20+
- `timestamp`: The timestamp of when the notification was sent, used to sort notifications by date. This is automatically set by the notifications package when the notification is received.
21+
- `callToAction`: An optional field that includes a title and a URL, providing a link for the user to take action on the notification. Part of the notification payload.
22+
- `title`: The title of the call to action.
23+
- `url`: The URL for the call to action.
24+
- `errors`: An optional field that includes an error message, providing additional information about the notification. If provided, the notification will not be shown in the inbox. Part of the notification payload.
25+
- `icon`: An optional field that includes an icon URL, used to display an icon for the notification. If not provided, the icon of the package that sent the notification will be used. Part of the notification payload.
26+
27+
---
28+
29+
### **Example Notification Payload**
30+
31+
```json
32+
{
33+
"title": "string", // e.g., "Geth Ethereum Node Sync Status"
34+
"body": "string", // e.g., "Triggered: Geth Ethereum Node Syncing"
35+
"category": "string", // e.g., "ethereum"
36+
"dnpName": "string", // e.g., "geth.dnp.dappnode.eth"
37+
"seen": false, // e.g., false
38+
"timestamp": "string", // e.g., "2023-10-01T12:00:00Z"
39+
"callToAction": {
40+
"title": "string", // e.g., "View Logs"
41+
"url": "string" // e.g., "http://dappmanager.dappnode/packages/my/geth.dnp.dappnode.eth/logs"
42+
},
43+
"errors": "string", // e.g., "Error: no such host: geth.dappnode"
44+
"icon": "string" // e.g., "https://gateway.ipfs.dappnode.io/ipfs/QmTVc5LQkTuaN3VxcteQ2E27pHSVJakE6XPo2FMxQTP284"
45+
}
46+
```
47+
48+
---
49+
50+
## **Notifications Package API**
51+
52+
The notifications package exposes an API that allows other packages to send notifications. This 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:
53+
54+
```
55+
http://notifier.notifications.dappnode:8080/api/v1/notifications
56+
```
57+
58+
### **Example API Request**
59+
60+
```bash
61+
curl -X POST \
62+
http://notifier.notifications.dappnode:8080/api/v1/notifications \
63+
-H 'Content-Type: application/json' \
64+
-d '{
65+
"title": "Test Notification",
66+
"body": "This is a test notification sent with curl",
67+
"category": "other",
68+
"dnpName": "test.dnp.dappnode.eth",
69+
"callToAction": {
70+
"title": "Hello World",
71+
"url": "http://dappmanager.dappnode"
72+
},
73+
"icon": "https://gateway.ipfs.dappnode.io/ipfs/QmTVc5LQkTuaN3VxcteQ2E27pHSVJakE6XPo2FMxQTP284"
74+
}'
75+
```
76+
77+
---
78+
79+
## **Notifications Inbox**
80+
81+
The notifications inbox is a place where users can see all the notifications that have been sent to them. Notifications are grouped by category and can be filtered by date, `dnpName`, and category. Users can also mark notifications as read or delete them.
82+
83+
![Notifications-Inbox](/img/notifications-inbox.png)
84+
85+
---
86+
87+
## **Notifications Settings**
88+
89+
The notifications settings allow users to configure the notifications they want to receive. Users can enable or disable notifications for each category and set thresholds for each notification. Thresholds determine when a notification should be sent. For example, if a user wants to receive a notification when CPU usage exceeds 80%, they can set the threshold to 80%. If the CPU usage goes above 80%, a notification will be sent.
90+
91+
![Notifications-Settings](/img/notifications-settings.png)
92+
93+
Furthermore, the notifications settings can be configured also during the installation process of the dappnode package.
94+
95+
![Notifications-Settings-installer](/img/notifications-settings-installer.png)
96+
97+
:::tip
98+
The notifications settings are persisted during the automatic update of the package.
99+
:::
100+
101+
---
102+
103+
## **Communication Channels**
104+
105+
Currently, the only communication channel available is the DAppNode UI. However, there are plans to implement additional communication channels, with the following priorities:
106+
107+
1. Web push notifications
108+
2. Telegram
109+
110+
---
111+
112+
Thanks for reading the guide! If you found some problem in the process, do not hesitate to contact us in Discord / Telegram.

0 commit comments

Comments
 (0)