Héberger ntfy sur un VPS : notifications push pour vos scripts

Uptime Kuma surveille vos services, Beszel surveille vos métriques VPS, Backrest gère vos sauvegardes, et vos cron jobs se taisent la nuit — sauf quand ils échouent. Chacun a son canal de notification : Slack, e-mail, webhook, Telegram. Résultat : cinq intégrations différentes à maintenir, cinq formats d'alertes à lire, et aucune vue unifiée quand quelque chose casse à 03h00. ntfy résout ce problème à l'envers : c'est vous qui hébergez le hub de notifications, et chaque outil ou script y envoie ses alertes en HTTP brut. Un seul topic à écouter sur votre téléphone, zéro dépendance à un service tiers.

ntfy est un binaire Go qui tient en un seul conteneur Docker. Il expose une interface HTTP simple : PUT ou POST sur /votre-topic publie un message ; n'importe quel client qui écoute ce topic (via WebSocket, SSE ou l'app mobile) le reçoit instantanément. Les messages sont mis en cache dans SQLite (/var/lib/ntfy/cache.db) avec une rétention configurable (12 heures par défaut). Pour la production, ntfy s'attend à être placé derrière un reverse proxy nginx qui gère le TLS — le paramètre behind-proxy: true dans server.yml indique à ntfy de lire l'IP réelle depuis X-Forwarded-For. L'ensemble de la configuration avancée — authentification, SMTP, access control — vit dans un seul fichier /etc/ntfy/server.yml monté en volume Docker.

Par défaut, ntfy démarre sans contrôle d'accès : la doc indique que auth-default-access vaut read-write, donc n'importe qui connaissant l'URL peut lire et écrire. En production, trois niveaux de protection s'empilent : d'abord auth-default-access: deny-all qui ferme le serveur à tout inconnu ; ensuite des utilisateurs créés via ntfy user add avec des mots de passe hachés stockés dans user.db (bcrypt, jamais en clair) ; enfin des tokens d'accès (ntfy token add) liés à un utilisateur spécifique, révocables indépendamment du mot de passe. Un token compromis se révoque sans changer le mot de passe de l'utilisateur. Les ACL par topic (ntfy access) permettent de cloisonner : l'utilisateur backrest ne peut écrire que sur backups, il ne voit pas server-alerts.

ntfy supporte plusieurs « espaces » sur le même serveur via les namespaces de topics. Créez un utilisateur par service ou par équipe, accordez-lui les droits uniquement sur ses topics, et chaque service croit avoir son propre hub. Exemple : l'utilisateur ci-bot a le droit rw sur ci-builds et ci-deploys ; l'utilisateur ops-bot a le droit rw sur server-alerts et cron-jobs. L'admin (rôle admin) voit tout. La séparation est purement logique — un seul processus ntfy, une seule base SQLite, une seule URL de base. Pour des équipes vraiment séparées qui ne doivent pas partager l'instance, déployez deux conteneurs ntfy sur deux sous-domaines distincts.

1. HTTP 403 Forbidden à l'envoi ou à la lecture
Message : {"code":40301,"http":403,"error":"Unauthorized"}
Cause : auth-default-access: deny-all est actif et le token manque ou est expiré. Vérifiez l'en-tête : curl -v -H "Authorization: Bearer tk_..." https://ntfy.exemple.com/mon-topic. Si le token est absent du header, le serveur rejette silencieusement. Régénérez le token avec ntfy token add <utilisateur> et mettez à jour vos scripts.

2. Notification envoyée mais jamais reçue sur mobile
Sur Android, vérifiez d'abord que l'app est abonnée à votre instance et non au serveur public ntfy.sh (URL dans les paramètres de l'app). Sur iOS, la cause la plus probable est l'absence de upstream-base-url: "https://ntfy.sh" dans server.yml : sans ce relais, la doc prévient que la livraison peut prendre des heures. Configurez-le, puis déroulez la checklist de la section iOS plus bas. base-url doit aussi être défini, mais la doc le relie aux URL de pièces jointes et au pied des e-mails, pas à l'arrivée du push.

3. Liens incorrects dans les e-mails sortants
Les e-mails SMTP envoyés par ntfy contiennent des liens vers les notifications. Sans base-url dans server.yml, le pied de l'e-mail (lien vers la notification) est construit sans l'URL publique et reste inutilisable depuis l'extérieur. Solution : définir base-url: https://ntfy.exemple.com et redémarrer le conteneur.

4. WebSocket drops répétés en production (reconnexions toutes les 30 s)
Cause : le timeout keepalive de nginx est inférieur à l'intervalle de heartbeat de ntfy (keepalive-interval: "45s" dans la configuration d'exemple de la doc). Le proxy ferme la connexion WebSocket avant que ntfy ne puisse envoyer son heartbeat. Ajoutez dans le bloc location nginx : proxy_read_timeout 60; et proxy_send_timeout 60;. Vérifiez aussi que proxy_http_version 1.1; et proxy_set_header Upgrade $http_upgrade; sont présents — sans eux, WebSocket est dégradé en long-polling SSE.

5. OOM (Out of Memory) sur un topic à très haut débit
ntfy garde les messages récents en mémoire avant de les écrire dans SQLite. Sur un topic qui reçoit des centaines de messages par seconde (ex. logs en temps réel mal filtrés), le buffer mémoire peut saturer un VPS à 512 Mo. Solution immédiate : réduire cache-duration à 1h ou 30m pour ce serveur. Solution structurelle : ne jamais utiliser ntfy comme système de log en temps réel — utilisez un filtre côté script (| grep -E 'ERROR|WARN') pour ne pousser que les événements pertinents. Pour les déploiements à très haut débit, ntfy peut utiliser PostgreSQL à la place de SQLite pour ses stockages (voir la doc de configuration).

Sur iOS, une app ne peut pas garder une connexion ouverte en arrière-plan : la documentation ntfy explique que cette restriction rend impossible un push instantané sans serveur central. Votre serveur auto-hébergé transmet donc, pour chaque message, une requête de « poll » à un serveur amont, ntfy.sh par défaut, qui se charge de réveiller l'app. Le réglage s'appelle upstream-base-url: "https://ntfy.sh". Cette requête ne contient que l'identifiant du message (en-tête X-Poll-ID) et l'empreinte SHA-256 de l'URL du topic, jamais le texte : le serveur auto-hébergé envoie littéralement « New message », et l'app va chercher le vrai contenu chez vous. Sans upstream-base-url, la documentation prévient que les notifications finissent par arriver, mais que la livraison peut prendre des heures (20 à 30 minutes si le téléphone est activement utilisé). Le paramètre upstream-access-token est facultatif : la doc ne le réserve qu'au cas où les limites du serveur amont sont dépassées ou si celui-ci est protégé.

Ces deux issues du dépôt ntfy décrivent le symptôme que vous cherchez : un serveur auto-hébergé, un push iOS qui ne s'affiche pas, des messages qui n'apparaissent qu'en rafraîchissant l'app à la main. Lues le 30 octobre 2026, elles sont toutes deux ouvertes et aucune ne désigne une cause confirmée.

#1305 « No push notifications on ios? » (ouverte en mars 2025, étiquettes ios et bug). Le rapporteur n'obtient aucune bannière, ni avec ntfy.sh ni avec sa propre instance. Des commentaires disent qu'une réinstallation de l'app a aidé, d'autres que le problème est revenu des mois plus tard. Un contributeur propose que l'app se réabonne aux topics Firebase au lancement et a ouvert une PR brouillon, en précisant qu'il n'a pas pu la tester. Un mainteneur demande au rapporteur si l'abonnement Firebase est en cause, sans conclure.

#1844 « No iOS Push notification, also with valid subscription » (ouverte en juillet 2026, étiquettes ios, server et bug). Le rapporteur fait tourner ntfy dans Docker avec NTFY_UPSTREAM_BASE_URL sur https://ntfy.sh et NTFY_UPSTREAM_ACCESS_TOKEN renseigné. Il dit avoir atteint la limite gratuite de 250 messages par jour, puis pris un abonnement payant. Ses journaux montrent le message publié et envoyé au relais, et pourtant aucun push. Un contributeur répond que des erreurs 429 peuvent valoir un bannissement d'IP pouvant durer jusqu'à 4 heures, constate que le test curl du rapporteur passe (donc pas de bannissement), et que le compte affichait 48 messages envoyés sur 2 500. Il ajoute que les notifications iOS sont capricieuses sans que l'on sache exactement pourquoi. Contournement rapporté : désactiver puis réactiver « Actualisation en arrière-plan » et « Notifications » dans les réglages iOS. L'auteur écrit ne pas savoir pourquoi cela marche ; le problème est revenu, puis reparti sans cause connue, et un autre utilisateur confirme le contournement en septembre 2026. Un autre rapport relie un cas voisin à des listes de blocage DNS.

Ce qu'on peut en conclure, et ce qu'on ne peut pas. Ni une limite de messages par jour ni un blocage 429 ne sont établis comme cause dans ces fils : le 429 n'y est écarté pour l'IP du rapporteur, et la limite de 250 messages est un chiffre donné par lui, pas par la documentation de configuration. Le jeton amont n'y règle pas le problème. Traitez donc la liste ci-dessus comme des vérifications, pas comme un correctif garanti.

Backrest est le gestionnaire d'interface web pour les sauvegardes Restic. Il supporte nativement ntfy comme type de hook : configurez l'URL du topic et le token Bearer dans l'interface Backrest, et chaque snapshot réussie ou échouée génère automatiquement une notification push avec le nom de la snapshot, la taille dédupliquée et la durée. C'est le cas d'usage le plus propre : zero script, zero cron, l'intégration est dans l'outil lui-même.

Uptime Kuma supporte ntfy nativement dans son gestionnaire de notifications. La configuration prend moins d'une minute : nom d'utilisateur + mot de passe (ou laissez vide et ajoutez Authorization: Bearer dans les headers personnalisés). Chaque monitor (HTTP, port TCP, ping, certificat TLS) peut avoir plusieurs canaux de notification — combinez ntfy pour le push mobile et l'e-mail SMTP de ntfy pour la traçabilité.

Grafana utilise les webhooks génériques. Créez un contact point de type webhook, pointez sur https://ntfy.exemple.com/grafana, ajoutez l'en-tête Authorization: Bearer tk_... et Content-Type: text/plain. Les alertes Grafana (CPU > 90%, latence P99, disk > 80%) arrivent immédiatement sur votre téléphone avec le nom de la règle dans le titre.