Ospitare ntfy su un VPS gestito significa inviare notifiche push con una semplice richiesta HTTP, PUT o POST, da una macchina tutta vostra, che i nostri team tengono aggiornata e supervisionano giorno e notte. ntfy è un software libero con doppia licenza, Apache 2.0 e GPLv2. Questa guida segue la sua documentazione ufficiale alla versione 2.38.1: l'installazione con Docker Compose, il file server.yml, gli utenti e il controllo degli accessi, i token di accesso, HTTPS, le app mobili, l'e-mail, i backup e gli aggiornamenti.
Di Simon Vasconcelos Lee
Pubblicato il 21 novembre 2026Lettura: 15 minuti
binwiederhier/ntfy, un server.yml con base-url, cache-file e auth-file, e la porta pubblicata su 127.0.0.1 dietro un reverse proxy in HTTPS.auth-default-access: deny-all, create un amministratore con ntfy user add, poi date a ogni script il proprio token e permessi limitati.server.yml e user.db, che contengono la configurazione, gli utenti, i permessi e i token; aggiornate cambiando il tag dell'immagine, dopo aver letto le note di rilascio.ntfy, che si pronuncia come «notify», è un servizio di notifiche publish-subscribe basato su HTTP. Il suo README lo presenta come un modo di inviare notifiche al telefono o al computer da script, da qualsiasi macchina. Il progetto gestisce un'istanza pubblica, ntfy.sh, e il server può essere self-hosted: è ciò di cui tratta questa guida.
curl, da uno script, da un'attività pianificata o da un'altra applicazione. Un messaggio può avere un titolo, una priorità da 1 a 5, tag ed emoji, un allegato, pulsanti di azione o un orario di consegna differito.ntfy o l'API, tramite WebSocket o un flusso HTTP che resta aperto.curl -d "Backup finished" https://ntfy.example.com/backups
Il README di ntfy indica che il progetto ha una doppia licenza: la Apache License 2.0, nel file LICENSE, e la GNU GPL versione 2, in LICENSE.GPLv2. L'immagine Docker le dichiara entrambe, Apache-2.0, GPL-2.0.
Far girare ntfy sul vostro server, per la vostra azienda, il vostro team o i vostri clienti, non richiede quindi alcuna licenza da acquistare. Entrambi i testi forniscono il software senza garanzia.
La licenza copre il codice. Il nome è un'altra questione: la Apache License 2.0 non concede alcun diritto sui marchi del licenziante, e i termini di servizio di ntfy.sh indicano che il nome, il logo e l'identità visiva di ntfy sono marchi di ntfy LLC, il cui uso in relazione a un prodotto o a un servizio richiede il suo consenso preventivo scritto. Questa guida nomina ntfy per descrivere il software.
Questa pubblicazione è indipendente dal progetto ntfy e da ntfy LLC, e non è affiliata, sponsorizzata né approvata da loro.
Il server è un unico binario collegato staticamente, per amd64, armv7 e arm64; l'immagine Docker esiste anche per armv6. La documentazione non indica alcun valore di memoria o di CPU: per un server domestico, dice, la scala non è motivo di preoccupazione. Indica invece ciò che limita un'istanza:
nofile. Il servizio systemd del pacchetto lo imposta a 10.000.Su un VPS gestito, parlateci del vostro utilizzo, del numero di dispositivi iscritti, del volume di messaggi e degli allegati, e vi raccomandiamo la taglia adatta.
La documentazione propone l'immagine binwiederhier/ntfy su Docker Hub. Serve l'app web e l'API sulla porta 80 del container, e non contiene alcun file server.yml: la configurazione va in una cartella montata su /etc/ntfy. Su un server in cui Docker è installato, create una cartella e collocatevi questo compose.yaml, basato sull'esempio della documentazione:
services:
ntfy:
image: binwiederhier/ntfy:v2.38.1
container_name: ntfy
command:
- serve
environment:
- TZ=UTC
volumes:
- ./etc:/etc/ntfy
- ./lib:/var/lib/ntfy
ports:
- "127.0.0.1:2586:80"
healthcheck:
test: ["CMD-SHELL", "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '\"healthy\"\\s*:\\s*true' || exit 1"]
interval: 60s
timeout: 10s
retries: 3
start_period: 40s
restart: unless-stopped
init: true
Poi il file di configurazione, in etc/server.yml, con l'indirizzo pubblico del vostro server:
base-url: "https://ntfy.example.com"
cache-file: "/var/lib/ntfy/cache.db"
attachment-cache-dir: "/var/lib/ntfy/attachments"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
behind-proxy: true
enable-login: true
docker compose up -d
curl http://127.0.0.1:2586/v1/health
Il server risponde {"healthy":true,"role":"active"}. Che cosa fa ogni impostazione:
127.0.0.1:2586: gli esempi Docker della documentazione pubblicano la porta 80 su tutti gli indirizzi, e i suoi esempi di reverse proxy inoltrano verso 127.0.0.1:2586. Pubblicata così, la porta si raggiunge solo dal server stesso, e l'API si raggiunge unicamente tramite il reverse proxy, in HTTPS.base-url: l'indirizzo pubblico del servizio. Il file server.yml di esempio lo richiede per gli allegati, l'invio di e-mail e le notifiche iOS da un server self-hosted.cache-file: senza di esso, i messaggi restano in memoria per 12 ore e vanno persi al riavvio. Questa cache permette ai telefoni con una connessione instabile di recuperare i messaggi che hanno perso.attachment-cache-dir: attiva gli allegati. ntfy prende il pieno controllo di questa cartella, quindi riservatela a questo uso.auth-file e auth-default-access: deny-all: il database degli utenti e dei permessi, creato al primo avvio, e l'accesso anonimo negato per impostazione predefinita. È l'impostazione che la documentazione raccomanda per un'istanza privata.behind-proxy: senza di esso, dietro un proxy, tutti i visitatori condividono l'indirizzo IP del proxy e gli stessi limiti di frequenza.enable-login: permette di accedere all'app web. La registrazione aperta resta chiusa, perché enable-signup vale false per impostazione predefinita.v2.38.1 fissa la versione; latest segue la versione più recente. La documentazione propone anche user: UID:GID per un account diverso da root: i file in etc e lib appartengono allora a quell'account.Il progetto pubblica anche un repository di pacchetti, firmato con la chiave di impronta 55BA 774A 6F5E E674 31E4 B6B7 CFDB 962D 4F1E C4AF. Su un server amd64:
sudo mkdir -p /etc/apt/keyrings
sudo curl -L -o /etc/apt/keyrings/ntfy.gpg https://archive.ntfy.sh/apt/keyring.gpg
sudo apt install apt-transport-https
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/ntfy.gpg] https://archive.ntfy.sh/apt stable main" \
| sudo tee /etc/apt/sources.list.d/ntfy.list
sudo apt update
sudo apt install ntfy
sudo systemctl enable ntfy
sudo systemctl start ntfy
Il pacchetto legge /etc/ntfy/server.yml. Il file di esempio raccomanda /var/cache/ntfy/cache.db per la cache e /var/lib/ntfy/user.db per gli utenti, due cartelle che il pacchetto crea. Dietro un proxy, aggiungete listen-http: "127.0.0.1:2586".
Di base, un server ntfy è aperto: chiunque può leggere e scrivere su tutti i topic, e il nome del topic fa da password. Con auth-file e deny-all, non passa nulla senza credenziali. ntfy ha due ruoli: admin, che legge e scrive su tutti i topic, e user, che ha solo i permessi che gli concedete.
docker compose exec ntfy ntfy user add --role=admin alice
Il comando chiede la password, poi la sua conferma. I comandi ntfy user, ntfy access e ntfy token scrivono direttamente nel database degli utenti: girano sul server, qui dentro il container, che legge il percorso di quel database in server.yml.
Al momento, un token di accesso dà pieno accesso all'account del suo utente, tranne per cambiare la password ed eliminare l'account. Per uno script, create un utente dedicato, limitato ai suoi topic, poi un token per lui:
docker compose exec ntfy ntfy user add backup-server
docker compose exec ntfy ntfy access backup-server backups write-only
docker compose exec ntfy ntfy token add --label="backups" backup-server
read-write, read-only, write-only o deny, su un topic preciso o su uno schema come alerts-*, l'unico carattere jolly supportato.everyone, o *. Per UnifiedPush su un'istanza privata, la documentazione apre in sola scrittura i topic che iniziano con up: ntfy access '*' 'up*' write-only.tk_, possono scadere con --expires=30d, e ogni utente può conservarne fino a 60. ntfy token list li elenca, ntfy token remove ne elimina uno.auth-users, auth-access e auth-tokens creano gli stessi oggetti da server.yml, a ogni avvio. Un utente tolto da quell'elenco viene eliminato dal database al riavvio successivo.Lo script pubblica poi con il suo token, in HTTPS:
curl \
-H "Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" \
-H "Title: Backup finished" \
-H "Priority: high" \
-d "The nightly backup went fine." \
https://ntfy.example.com/backups
Una password in Basic auth è solo codificata in base64, non cifrata: la documentazione chiede HTTPS su ogni server self-hosted. È l'argomento della sezione successiva.
ntfy può servire HTTPS da solo, ma dietro un proxy la documentazione raccomanda di lasciare la terminazione TLS al proxy. Due punti contano più di tutto il resto:
Upgrade e Connection, e lascia vivere queste connessioni lunghe. ntfy invia per impostazione predefinita un messaggio keepalive ogni 45 secondi, keepalive-interval, perché nessun intermediario le chiuda per inattività.behind-proxy: true, ntfy legge l'intestazione X-Forwarded-For e tiene l'indirizzo più a destra, quello che aggiunge il vostro proxy. I limiti di frequenza si applicano a quell'indirizzo.La documentazione osserva che Caddy gestisce sia HTTP sia WebSocket con reverse_proxy, senza impostazioni aggiuntive. Ottiene da solo il certificato Let's Encrypt:
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}
Questo blocco segue la configurazione della documentazione, vicina a quella usata da ntfy.sh: il buffering disattivato per i flussi, timeout di 3 minuti e nessun limite di dimensione sul corpo delle richieste, che ntfy limita da solo. Ascolta sulla porta 80 per lasciare a Certbot l'attivazione di HTTPS:
server {
listen 80;
listen [::]:80;
server_name ntfy.example.com;
location / {
proxy_pass http://127.0.0.1:2586;
proxy_http_version 1.1;
proxy_buffering off;
proxy_request_buffering off;
proxy_redirect off;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_connect_timeout 3m;
proxy_send_timeout 3m;
proxy_read_timeout 3m;
client_max_body_size 0;
}
}
sudo ln -s /etc/nginx/sites-available/ntfy /etc/nginx/sites-enabled/
sudo nginx -t
sudo certbot --nginx -d ntfy.example.com
Una volta che HTTP reindirizza verso HTTPS, pubblicate su indirizzi https:// nei vostri script. Per migliaia di iscritti, la documentazione alza worker_connections in nginx.conf e il LimitNOFILE del servizio Nginx, al doppio delle connessioni che si vogliono sostenere.
Le app ntfy aggiungono i topic del vostro server come quelli di ntfy.sh: inserite il suo indirizzo quando aggiungete il topic e, per un topic protetto, il nome utente e la password di un utente che vi ha accesso. L'app web è servita all'indirizzo stesso del server.
ntfy webpush keys e un certificato HTTPS valido.Aggiungete una riga a server.yml, poi riavviate il container:
upstream-base-url: "https://ntfy.sh"
Per ogni messaggio, il vostro server pubblica allora su ntfy.sh una richiesta di polling, che contiene solo l'ID del messaggio e l'hash SHA-256 dell'URL del topic. ntfy.sh la trasmette al dispositivo tramite il servizio di notifiche di Apple, poi l'app recupera il messaggio dal vostro server. Il testo che passa da ntfy.sh è sempre lo stesso, «New message», qualunque cosa dica il vostro. Senza questa impostazione, le notifiche arrivano comunque, con un ritardo che può raggiungere diverse ore a seconda dello stato del telefono. upstream-access-token aggiunge un token se superate i limiti di frequenza di ntfy.sh.
ntfy limita ogni visitatore, identificato dal suo indirizzo IP e, in IPv6, dalla sua sottorete /64. Questi limiti proteggono il server dagli abusi; in un uso normale, dice la documentazione, non dovreste raggiungerli. Oltre, il server risponde 429 Too Many Requests. I valori predefiniti:
| Impostazione | Predefinito | Che cosa limita |
|---|---|---|
visitor-request-limit-burst | 60 | Le richieste di un visitatore in una raffica |
visitor-request-limit-replenish | 5s | Il ritmo di ricarica: una richiesta ogni 5 secondi |
visitor-subscription-limit | 30 | Le connessioni aperte per visitatore |
visitor-message-daily-limit | Nessuno | I messaggi al giorno, altrimenti regolati dal limite di richieste |
visitor-email-limit-burst | 16 | Le e-mail in una raffica, poi una all'ora |
visitor-attachment-total-size-limit | 100M | Lo spazio per gli allegati per visitatore |
visitor-attachment-daily-bandwidth-limit | 500M | Il traffico degli allegati per visitatore al giorno |
global-topic-limit | 15.000 | Il numero totale di topic del server |
message-size-limit | 4K | La dimensione di un messaggio; oltre, diventa un allegato |
visitor-request-limit-exempt-hosts, un elenco di indirizzi IP o di nomi host.ntfy tier, danno ad alcuni account limiti più alti.attachment-file-size-limit, 15M per impostazione predefinita, limita ogni file, attachment-total-size-limit, 5G, lo spazio complessivo, e attachment-expiry-duration, 3h, la loro durata. Un allegato non sopravvive mai al suo messaggio: per conservare gli allegati più a lungo, alzate anche cache-duration.ntfy può inoltrare un messaggio via e-mail quando la richiesta di pubblicazione porta l'intestazione Email, o X-Email, con un indirizzo. Per farlo passa da un server SMTP in uscita, in STARTTLS, con autenticazione PLAIN o LOGIN: è la porta 587. Da un VPS Simafri, l'e-mail esce tramite un relay SMTP autenticato su quella stessa porta 587: configurate qui l'indirizzo di un account e-mail che avete già, oppure quello del vostro servizio di invio di e-mail.
smtp-sender-addr: "smtp.example.com:587"
smtp-sender-user: "ntfy@example.com"
smtp-sender-pass: "smtp-password"
smtp-sender-from: "ntfy@example.com"
curl \
-H "Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" \
-H "Email: alice@example.com" \
-d "The file server disk is over 90% full." \
https://ntfy.example.com/alerts
base-url e smtp-sender-from sono obbligatori non appena è impostato smtp-sender-addr: senza di essi, il server si rifiuta di avviarsi.smtp-sender-verify: true limita l'invio agli indirizzi che ogni utente ha verificato nel proprio account, e lo chiude agli utenti anonimi.server.yml: lasciate quel file leggibile solo dal suo proprietario, con chmod 600.Con SQLite, ntfy conserva ogni tipo di dati in un file a sé. Nell'installazione di questa guida, tutto si trova nelle cartelle etc e lib, accanto al compose.yaml:
| Elemento | Che cosa conserva | Da salvare |
|---|---|---|
etc/server.yml | La configurazione, compresi i segreti SMTP e le chiavi Web Push | Sì |
lib/user.db | Utenti, voci di controllo degli accessi, token e contatori giornalieri | Sì |
lib/cache.db | I messaggi delle ultime 12 ore, per impostazione predefinita | Utile, la sua durata è breve |
lib/attachments/ | Gli allegati delle ultime 3 ore, per impostazione predefinita | Utile, la sua durata è breve |
File web-push-file | Le iscrizioni Web Push dei browser, se l'avete attivato | Sì |
Per una copia coerente dei file SQLite, fermate il servizio mentre viene creato l'archivio:
docker compose stop
tar -czf ntfy-$(date +%F).tar.gz compose.yaml etc lib
docker compose start
Pianificate questa copia in un orario tranquillo, e inviatela fuori dal server. Collocati sul suo disco, questi archivi rientrano anche nei suoi backup notturni. Per ripristinare, rimettete le cartelle al loro posto, poi lanciate docker compose up -d.
Se perdete user.db senza alcuna copia, gli utenti e i token dichiarati in server.yml tramite auth-users e auth-tokens vengono ricreati all'avvio; quelli creati dalla riga di comando vanno creati di nuovo.
Con Docker, cambiate il tag dell'immagine in compose.yaml, per esempio da v2.38.1 alla versione successiva, poi:
docker compose pull
docker compose up -d
Le cartelle etc e lib restano al loro posto, e ntfy migra da solo i suoi database all'avvio. Con il pacchetto Debian, sudo apt update poi sudo apt upgrade fanno lo stesso.
Le note di ogni versione, nella pagina «Releases» della documentazione, raccolgono in «Upgrade notes» ciò che cambia per un'istanza esistente, come, nella 2.36.0, una configurazione ora verificata per intero all'avvio, o i contatori giornalieri azzerati. Leggetele prima di aggiornare, e copiate le due cartelle subito prima. La versione 2.38.1 è una versione di sicurezza, fortemente raccomandata dal progetto: rafforza i modelli dei messaggi contro gli attacchi di negazione del servizio e impedisce che i caricamenti lenti di allegati verso S3 e gli endpoint web push che non rispondono tengano occupate memoria e connessioni. Segue la 2.38.0, che condivide i limiti di frequenza tra i nodi di un cluster ed è compilata con Go 1.27.4.
Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; ntfy resta il vostro software, con le sue impostazioni e i suoi dati.
| Argomento | I nostri team | Voi |
|---|---|---|
| Il server | Aggiornamenti del sistema e della sicurezza, interventi sul server compresi | Il momento più adatto alla vostra attività |
| La supervisione | Server seguito 24 ore su 24, 7 giorni su 7, con intervento senza attendere la vostra chiamata | La lettura dei log della vostra istanza |
| ntfy | Monitoraggio proattivo: errori, rallentamenti, connessioni aperte e spazio su disco individuati, correzione raccomandata | La sua installazione, i suoi aggiornamenti e le sue impostazioni, che applicate voi o il vostro assistente IA |
| Gli accessi | Il server che lo ospita, sorvegliato e salvato | Gli utenti, i permessi sui topic e i token dei vostri script |
| I backup | Ogni notte, cifrati e conservati fuori dalla macchina; ripristino compreso | Le copie proprie di ntfy e la richiesta di ripristino, quando ne avete bisogno |
| La migrazione | Il vostro server attuale migrato, in omaggio | Il momento del passaggio |
Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.
Con un VPS gestito Simafri, i nostri team tengono aggiornato il server della vostra istanza ntfy, lo sorvegliano giorno e notte e intervengono senza attendere la vostra chiamata; seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi o il vostro assistente IA. I backup sono cifrati ogni notte e conservati fuori dalla macchina, il loro ripristino è compreso e la migrazione del vostro server attuale è in omaggio.
Sì. ntfy ha una doppia licenza, Apache 2.0 e GPLv2: potete farlo girare in azienda senza alcuna licenza da acquistare. Le loro condizioni si applicano alla ridistribuzione del software. Resta il costo del server che lo fa girare.
Create un compose.yaml con l'immagine binwiederhier/ntfy, il comando serve, una cartella montata su /etc/ntfy per server.yml, un'altra su /var/lib/ntfy per i database, e la porta 80 del container pubblicata su 127.0.0.1:2586. Lanciate docker compose up -d, poi collocate un reverse proxy in HTTPS davanti a quella porta.
In server.yml, impostate auth-file e auth-default-access: deny-all. Create poi un amministratore con ntfy user add --role=admin, utenti limitati con ntfy user add, e i loro permessi sui topic con ntfy access.
Create un token con ntfy token add per un utente dedicato allo script, limitato ai suoi topic, poi pubblicate con curl e l'intestazione Authorization: Bearer seguita dal token, in HTTPS. Un token dà accesso all'intero account del suo utente.
Dietro un reverse proxy, ogni richiesta arriva dall'indirizzo del proxy. Con behind-proxy: true, ntfy legge l'intestazione X-Forwarded-For per identificare ogni visitatore; senza, condividono tutti gli stessi limiti di frequenza.
Sì, con upstream-base-url: "https://ntfy.sh" in server.yml. Il vostro server fa allora inoltrare da ntfy.sh un segnale che contiene solo l'ID del messaggio, e l'app recupera il messaggio dal vostro server. Senza questa impostazione, la consegna può richiedere diverse ore.
Salvate server.yml e user.db, che contengono la configurazione, gli utenti, i permessi e i token, più il file Web Push se è attivato. La cache dei messaggi e gli allegati hanno una durata breve. Fermate il servizio durante la copia, per avere file SQLite coerenti.
Un VPS gestito copre il server: sistema, sicurezza, supervisione e backup. I nostri team seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi. Un intervento nell'applicazione si fattura a ore o a forfait.
Simafri
Parliamo del vostro progetto
Diteci in due parole ciò che vi serve: vi rispondiamo rapidamente.
Grazie! La tua richiesta è stata inviata. Ti risponderemo a breve.
Preferite l'email? Scriveteci a support@simafri.com.