250 lines
9.6 KiB
Markdown
250 lines
9.6 KiB
Markdown
# ntfy-bridge
|
|
|
|
Hub central de notifications pour homelab — agrège des sources multiples (Gitea, Docker, Uptime Kuma, health checks HTTP, scripts cron) et les transforme en notifications [Ntfy](https://ntfy.sh/) intelligentes, formatées, avec priorités et contexte.
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Gitea webhook │──┐
|
|
├─────────────────┤ │
|
|
│ Uptime Kuma │──┤
|
|
├─────────────────┤ │ ┌──────────────┐ ┌───────────┐ ┌──────────────┐
|
|
│ Docker events │──┤────→│ ntfy-bridge │─────→│ Ntfy Srv │─────→│ Ton phone │
|
|
├─────────────────┤ │ └──────────────┘ └───────────┘ └──────────────┘
|
|
│ HTTP health │──┤
|
|
├─────────────────┤ │
|
|
│ Scripts cron │──┘
|
|
└─────────────────┘
|
|
```
|
|
|
|
## Pourquoi ntfy-bridge ?
|
|
|
|
Dans un homelab avec 8+ hôtes Docker, Gitea, Uptime Kuma et des dizaines de services, les alertes arrivent de partout. `ntfy-bridge` centralise tout dans une seule file de notifications intelligentes — avec le bon niveau de priorité, le bon format, et le bon topic Ntfy.
|
|
|
|
| Sans ntfy-bridge | Avec ntfy-bridge |
|
|
|---|---|
|
|
| Webhook Gitea → email (noyé) | Push = notif Ntfy formatée avec auteur, commit, message |
|
|
| Uptime Kuma → alerte brute | "🚨 Gitea DOWN — 503 — since 14:32" avec priority=5 |
|
|
| Container qui crashe → logs Docker | "🐳 flowdeck exited OOMKilled on docker-prod-1" |
|
|
| Script cron → email perdu | Résumé quotidien disque à 9h dans ta poche |
|
|
|
|
## Installation
|
|
|
|
Les binaires pré-compilés sont disponibles sur le dépôt Nexus :
|
|
|
|
```
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/{VERSION}/
|
|
```
|
|
|
|
Remplacer `{VERSION}` par la version souhaitée (ex: `v0.7.0`).
|
|
Chaque release contient trois binaires statiques — **zéro dépendance** :
|
|
|
|
| Fichier | Plateforme |
|
|
|---------|-----------|
|
|
| `ntfy-bridge-linux-x86_64` | Linux 64-bit (Intel/AMD) |
|
|
| `ntfy-bridge-linux-arm64` | Linux ARM64 (Raspberry Pi 3/4/5) |
|
|
| `ntfy-bridge-windows-x86_64.exe` | Windows 64-bit |
|
|
|
|
> 💡 **Pas besoin de V, Git, ni compilateur.** Les binaires sont compilés statiquement — un seul fichier, prêt à exécuter.
|
|
|
|
---
|
|
|
|
### Linux (x86_64)
|
|
|
|
#### Option A : Service système (recommandé)
|
|
|
|
```bash
|
|
# 1. Télécharger le binaire (remplacer v0.7.0 par la version désirée)
|
|
sudo curl -fsSL -o /usr/local/bin/ntfy-bridge \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/ntfy-bridge-linux-x86_64
|
|
sudo chmod +x /usr/local/bin/ntfy-bridge
|
|
|
|
# 2. Créer le répertoire de config et copier l'exemple
|
|
sudo mkdir -p /etc/ntfy-bridge
|
|
sudo curl -fsSL -o /etc/ntfy-bridge/ntfy-bridge.yaml \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/ntfy-bridge.example.yaml
|
|
sudo curl -fsSL -o /etc/ntfy-bridge/dashboard.html \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/dashboard.html
|
|
|
|
# 3. Éditer la configuration
|
|
sudo vim /etc/ntfy-bridge/ntfy-bridge.yaml
|
|
|
|
# 4. Installer comme service systemd (ou openrc si détecté)
|
|
sudo ntfy-bridge --install-service --config /etc/ntfy-bridge/ntfy-bridge.yaml
|
|
|
|
# 5. Vérifier
|
|
curl http://localhost:9090/health
|
|
```
|
|
|
|
**Commandes utiles :**
|
|
```bash
|
|
systemctl status ntfy-bridge # État du service
|
|
systemctl restart ntfy-bridge # Redémarrer après modif de config
|
|
journalctl -u ntfy-bridge -f # Logs en temps réel
|
|
ntfy-bridge --uninstall-service # Désinstaller le service
|
|
```
|
|
|
|
#### Option B : Docker
|
|
|
|
```bash
|
|
# 1. Créer un dossier et générer la stack docker-compose
|
|
mkdir -p /opt/ntfy-bridge && cd /opt/ntfy-bridge
|
|
ntfy-bridge --install-docker .
|
|
|
|
# 2. Éditer la configuration
|
|
vim ntfy-bridge.yaml
|
|
|
|
# 3. Démarrer
|
|
docker compose up -d
|
|
|
|
# 4. Vérifier
|
|
curl http://localhost:9090/health
|
|
```
|
|
|
|
Ce que contient la stack Docker :
|
|
- Le binaire exposé sur `127.0.0.1:9090`
|
|
- `ntfy-bridge.yaml` monté en read-only dans `/etc/ntfy-bridge/`
|
|
- `dashboard.html` monté automatiquement
|
|
- Variables d'environnement `NTFY_TOKEN` et `NTFY_HMAC_SECRET`
|
|
- Healthcheck intégré (`/health` toutes les 30s)
|
|
- Redémarrage automatique (`restart: unless-stopped`)
|
|
|
|
---
|
|
|
|
### Raspberry Pi (ARM64)
|
|
|
|
Mêmes étapes que Linux, avec le binaire `linux-arm64` :
|
|
|
|
```bash
|
|
# 1. Télécharger le binaire ARM64
|
|
sudo curl -fsSL -o /usr/local/bin/ntfy-bridge \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/ntfy-bridge-linux-arm64
|
|
sudo chmod +x /usr/local/bin/ntfy-bridge
|
|
|
|
# 2. Récupérer la config et le dashboard
|
|
sudo mkdir -p /etc/ntfy-bridge
|
|
sudo curl -fsSL -o /etc/ntfy-bridge/ntfy-bridge.yaml \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/ntfy-bridge.example.yaml
|
|
sudo curl -fsSL -o /etc/ntfy-bridge/dashboard.html \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/dashboard.html
|
|
|
|
# 3. Éditer la config
|
|
sudo vim /etc/ntfy-bridge/ntfy-bridge.yaml
|
|
|
|
# 4. Installer le service
|
|
sudo ntfy-bridge --install-service --config /etc/ntfy-bridge/ntfy-bridge.yaml
|
|
|
|
# 5. Vérifier
|
|
curl http://localhost:9090/health
|
|
```
|
|
|
|
**Docker sur Raspberry Pi :** identique à l'option B Linux — le binaire est déjà dans l'image Docker, pas besoin de le télécharger séparément. Utiliser `ntfy-bridge --install-docker .` pour générer la stack.
|
|
|
|
---
|
|
|
|
### Windows
|
|
|
|
```powershell
|
|
# 1. Créer le dossier d'installation (PowerShell administrateur)
|
|
New-Item -ItemType Directory -Force -Path "$env:ProgramFiles\ntfy-bridge"
|
|
|
|
# 2. Télécharger le binaire Windows
|
|
Invoke-WebRequest -Uri "https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/ntfy-bridge-windows-x86_64.exe" `
|
|
-OutFile "$env:ProgramFiles\ntfy-bridge\ntfy-bridge.exe"
|
|
|
|
# 3. Télécharger la config et le dashboard
|
|
Invoke-WebRequest -Uri "https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/ntfy-bridge.example.yaml" `
|
|
-OutFile "$env:ProgramFiles\ntfy-bridge\ntfy-bridge.yaml"
|
|
Invoke-WebRequest -Uri "https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.7.0/dashboard.html" `
|
|
-OutFile "$env:ProgramFiles\ntfy-bridge\dashboard.html"
|
|
|
|
# 4. Éditer la configuration (dans le Bloc-notes)
|
|
notepad "$env:ProgramFiles\ntfy-bridge\ntfy-bridge.yaml"
|
|
|
|
# 5. Installer NSSM (requis pour le service Windows)
|
|
# Télécharger depuis https://nssm.cc/download
|
|
# ou avec scoop : scoop install nssm
|
|
# Placer nssm.exe dans le PATH ou dans $env:ProgramFiles\ntfy-bridge\
|
|
|
|
# 6. Installer comme service Windows
|
|
& "$env:ProgramFiles\ntfy-bridge\ntfy-bridge.exe" --install-service `
|
|
--config "$env:ProgramFiles\ntfy-bridge\ntfy-bridge.yaml"
|
|
|
|
# 7. Vérifier
|
|
Invoke-WebRequest -Uri http://localhost:9090/health
|
|
```
|
|
|
|
**Commandes utiles (PowerShell) :**
|
|
```powershell
|
|
nssm status ntfy-bridge # État du service
|
|
nssm restart ntfy-bridge # Redémarrer
|
|
nssm stop ntfy-bridge # Arrêter
|
|
nssm start ntfy-bridge # Démarrer
|
|
nssm remove ntfy-bridge confirm # Désinstaller le service
|
|
```
|
|
|
|
Logs du service : `C:\ProgramData\ntfy-bridge\service.log`
|
|
|
|
---
|
|
|
|
### Mise à jour
|
|
|
|
Pour mettre à jour vers une nouvelle version, remplacer le binaire et redémarrer :
|
|
|
|
```bash
|
|
# Linux / Raspberry Pi
|
|
sudo curl -fsSL -o /usr/local/bin/ntfy-bridge \
|
|
https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.8.0/ntfy-bridge-linux-x86_64
|
|
sudo chmod +x /usr/local/bin/ntfy-bridge
|
|
sudo systemctl restart ntfy-bridge
|
|
```
|
|
|
|
```powershell
|
|
# Windows (PowerShell administrateur)
|
|
nssm stop ntfy-bridge
|
|
Invoke-WebRequest -Uri "https://nexus.dracodev.net/repository/raw-hosted/ntfy-bridge/v0.8.0/ntfy-bridge-windows-x86_64.exe" `
|
|
-OutFile "$env:ProgramFiles\ntfy-bridge\ntfy-bridge.exe"
|
|
nssm start ntfy-bridge
|
|
```
|
|
|
|
## Sources supportées
|
|
|
|
| Source | Type | Description |
|
|
|--------|------|-------------|
|
|
| **Gitea** | Webhook | Push, PR, issues, releases → notifs formatées |
|
|
| **Uptime Kuma** | Webhook | Statut up/down avec priorité critique |
|
|
| **Docker** | Socket | Container start/die/oom/health_status |
|
|
| **HTTP Poll** | Polling | Health checks périodiques |
|
|
| **Cron** | Webhook | Reçoit des notifs depuis des scripts shell |
|
|
| **Generic** | Webhook | Endpoint passe-partout pour tout script custom |
|
|
| **Plugin** | Exec | Exécutable externe appelé périodiquement (bash, python, …) |
|
|
|
|
## Features
|
|
|
|
- **ACLs** — Restriction par IP (CIDR) ou Bearer token sur chaque webhook
|
|
- **Plugins** — Scripts externes exécutés toutes les 60s, contrat JSON stdout
|
|
- **Dashboard** — Interface web avec stats, statuts, historique temps réel
|
|
- **Filtres** — Règles conditionnelles drop/set_priority/add_tag par source
|
|
- **Actions Ntfy** — Boutons click, vues, broadcast intégrés
|
|
- **Prometheus** — Endpoint `/metrics` pour Grafana
|
|
- **Outgoing webhooks** — Forward vers Slack, Discord, JSON
|
|
- **Silence rules** — Mute temporaire des notifs via API
|
|
- **Grouping** — Regroupement intelligent des notifs identiques
|
|
- **State persistence** — Sauvegarde de l'état up/down et silence sur disque
|
|
|
|
## Exemple de config minimale
|
|
|
|
```yaml
|
|
server:
|
|
url: https://ntfy.dracodev.net
|
|
listen: ":9090"
|
|
|
|
sources:
|
|
gitea:
|
|
- webhook_path: /webhooks/gitea
|
|
topic: dev-notifs
|
|
```
|
|
|
|
## Licence
|
|
|
|
MIT
|