Como hospedar o ntfy para alertas de servidores

O que um servidor ntfy autogerido faz

Um servidor ntfy autogerido transforma um HTTP POST numa notificação push no seu telemóvel. Pode publicar com curl, e a mensagem chega à aplicação Android, à aplicação iOS, a um separador do navegador ou a qualquer outro cliente que consiga manter uma ligação HTTP aberta. Não é necessário instalar uma biblioteca de cliente nem executar um message broker.

O ntfy identifica as mensagens por tópico. Um tópico é um nome no caminho do URL, como https://ntfy.example.com/alerts, e passa a existir no momento em que alguém publica nele. Numa instalação predefinida, qualquer pessoa que conheça esse nome pode ler o tópico e escrever nele. Por isso, a documentação do próprio projeto compara o nome de um tópico a uma password. Esse modelo é adequado para o serviço público ntfy.sh. Não é adequado para um servidor que transporta falhas dos seus backups. Por isso, este guia ativa a autenticação antes de a primeira mensagem ser enviada.

O que é necessário antes de começar

Você precisa de um VPS com Ubuntu 24.04 ou Debian 13, Docker Engine e o plugin Compose instalados, um nome de domínio e muito pouca RAM. Crie um registo DNS (domain name system) do tipo A que aponte ntfy.example.com para o endereço IP público do servidor. Depois, confirme que o nome é resolvido antes de fazer qualquer outra alteração.

dig +short ntfy.example.com
sudo ufw allow 80,443/tcp
sudo ufw status

dig deve mostrar o IP do servidor. A emissão do certificado falha se não mostrar nada, porque a autoridade de certificação verifica o nome a partir do exterior. A porta 80 permanece aberta porque o ACME (automatic certificate management environment), o protocolo utilizado pelo Let's Encrypt, usa-a para o desafio HTTP. O contentor ntfy nunca fica exposto numa porta pública.

Escreva o ficheiro de configuração do ntfy

A imagem Docker não inclui um ficheiro de configuração, por isso é necessário criar um. Todos os comandos apresentados mais à frente neste guia leem esse ficheiro. Primeiro, obtenha o ID do utilizador e o ID do grupo com que o contentor será executado.

id -u
id -g
sudo install -d -o "$(id -u)" -g "$(id -g)" /etc/ntfy /var/cache/ntfy /var/lib/ntfy
sudo nano /etc/ntfy/server.yml

base-url: "https://ntfy.example.com"
listen-http: ":2586"
behind-proxy: true
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-login: true
enable-signup: false

Quatro dessas linhas são fundamentais. base-url tem de ser exatamente o endereço HTTPS público, porque o ntfy cria a partir dele os links para anexos e os pedidos da própria aplicação web. Um valor incorreto faz com que a aplicação web carregue, mas falhe em todas as ações. listen-http: ":2586" associa-se a todas as interfaces dentro do contentor. Isto parece descuidado, mas está correto: o contentor tem o seu próprio namespace de rede, por isso associar-se a 127.0.0.1 nesse contexto tornaria a porta inacessível a partir do anfitrião e a porta publicada pelo Docker nunca conseguiria estabelecer a ligação. auth-default-access: "deny-all" define toda a política de segurança, porque recusa operações de leitura e escrita a qualquer pessoa sem uma autorização explícita. behind-proxy: true indica ao ntfy que deve obter o endereço do cliente a partir do cabeçalho X-Forwarded-For. Assim, os limites de pedidos contam os visitantes reais, em vez de contarem o reverse proxy como um único cliente muito ativo.

enable-login: true permite que a aplicação web e as aplicações móveis iniciem sessão com uma palavra-passe. enable-signup permanece como false, porque permitir a criação autónoma de contas num servidor privado seria uma porta aberta com passos adicionais.

sudo chown "$(id -u):$(id -g)" /etc/ntfy/server.yml
sudo chmod 600 /etc/ntfy/server.yml

Executar o ntfy com Docker Compose

Coloque isto em /opt/ntfy/compose.yaml, substituindo 1000:1000 pelos dois números id -u e id -g apresentados acima.

services:
  ntfy:
    image: binwiederhier/ntfy:v2.27.0
    container_name: ntfy
    command: serve
    user: "1000:1000"
    environment:
      - TZ=UTC
    volumes:
      - /etc/ntfy:/etc/ntfy
      - /var/cache/ntfy:/var/cache/ntfy
      - /var/lib/ntfy:/var/lib/ntfy
    ports:
      - "127.0.0.1:2586:2586"
    restart: unless-stopped

cd /opt/ntfy
sudo docker compose up -d
sudo docker compose logs ntfy
curl -s http://127.0.0.1:2586/v1/health

Um servidor saudável responde a {"healthy":true}. Há dois detalhes deliberados nesse ficheiro Compose. A imagem está fixada em v2.27.0, a versão atual em agosto de 2026, em vez de latest, porque, com latest, o próximo docker compose pull altera a versão do servidor e só irá descobrir isso depois, ao consultar o changelog. A porta é publicada como 127.0.0.1:2586:2586, pelo que o contentor só pode ser acedido a partir do endereço de loopback do host. Escreva 2586:2586 e o Docker insere as suas próprias regras de firewall antes das suas, o que faz com que a porta responda a partir da Internet, apesar de ufw status indicar que a porta está fechada. Ambos os hábitos aplicam-se também ao próximo contentor que adicionar: um relay RustDesk self-hosted fixa a tag da imagem da mesma forma, mas não pode ficar protegido atrás do loopback, porque as portas de sinalização e de relay têm de responder a partir da Internet.

Se o curl imprimir Connection refused, leia o log do contentor. Um erro de permissões em /var/lib/ntfy/user.db significa que a linha user: não corresponde ao proprietário desses diretórios, pelo que o processo não consegue criar a sua própria base de dados e termina. O guia básico de Docker Compose para um VPS explica com mais detalhe a propriedade de volumes e as políticas de reinício.

Configure o TLS com o Caddy

O Caddy solicita e renova o certificado automaticamente. Esta é a forma mais simples de obter TLS (segurança da camada de transporte) funcional.

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Substitua o conteúdo de /etc/caddy/Caddyfile por três linhas.

ntfy.example.com {
    reverse_proxy 127.0.0.1:2586
}

sudo systemctl reload caddy
curl -s https://ntfy.example.com/v1/health

O mesmo {"healthy":true} por HTTPS confirma que todo o caminho está a funcionar. Um 502 do Caddy indica que o ntfy não está a escutar: verifique com sudo ss -lntp | grep 2586. Um erro de certificado normalmente significa que o registo DNS está incorreto ou que a porta 80 está bloqueada. sudo journalctl -u caddy -n 50 indica qual das duas situações ocorre. Para adicionar outro serviço mais tarde, basta incluir mais um bloco de hostname no mesmo Caddyfile. É assim que algo como Halcyon, um frontend de videoclube dos anos 90 para a sua biblioteca Jellyfin fica disponível num segundo subdomínio do mesmo servidor.

Se já utiliza nginx, copie as definições de proxy documentadas pelo ntfy: proxy_http_version 1.1, proxy_buffering off, proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for, e defina timeouts de leitura e envio de pelo menos três minutos. Um subscriber mantém uma ligação HTTP aberta enquanto estiver a escutar. Por predefinição, o nginx fecha uma ligação upstream inativa após 60 segundos. Por isso, os subscribers ligam-se novamente num ciclo e as mensagens enviadas durante o intervalo são perdidas.

Criar utilizadores e restringir o acesso aos tópicos

A autenticação está ativa e ninguém tem acesso a nada. Esse é o objetivo. Crie uma conta de administrador para si e uma conta de máquina para os scripts. Estes comandos leem /etc/ntfy/server.yml a partir do interior do contentor. É por isso que o ficheiro de configuração é montado como volume.

sudo docker compose exec ntfy ntfy user add --role=admin admin
sudo docker compose exec ntfy ntfy user add robot
sudo docker compose exec ntfy ntfy user list

Cada comando pede uma palavra-passe. Um administrador ignora a lista de controlo de acesso e pode ler e escrever em todos os tópicos. Por isso, reserve essa conta para si e para a aplicação do telemóvel. robot é um utilizador normal sem qualquer acesso até lhe conceder permissões.

sudo docker compose exec ntfy ntfy access robot alerts write
sudo docker compose exec ntfy ntfy access robot "alerts_*" write
sudo docker compose exec ntfy ntfy access

Uma ACL (lista de controlo de acesso) contém um utilizador, um tópico e uma permissão. O tópico pode ser um nome literal ou um padrão em que * corresponde a qualquer sequência. Assim, alerts_* abrange alerts_backup e alerts_db sem ser necessário executar um comando por anfitrião. A permissão write significa apenas publicar. Assim, um token roubado de uma tarefa cron não pode subscrever nem ler o que publicou. O nome de utilizador especial everyone define o que um visitante não autenticado pode fazer. Deve utilizá-lo apenas para abrir deliberadamente algo público, como ntfy access everyone status read.

Os scripts devem utilizar um token, não a sua palavra-passe.

sudo docker compose exec ntfy ntfy token add robot

O comando imprime um token que começa por tk_. Um token herda exatamente as permissões do utilizador a que pertence. Portanto, este token pode publicar nos tópicos alerts e não pode fazer mais nada. ntfy token list mostra o que existe, e ntfy token remove revoga um token sem alterar a palavra-passe do utilizador.

Envie a primeira mensagem e confirme que o bloqueio funciona

Comece por verificar se a porta está fechada.

curl -s -o /dev/null -w '%{http_code}\n' -d "hello" https://ntfy.example.com/alerts

Isto mostra 403, e 403 é a resposta correta: auth-default-access: "deny-all" recusa uma publicação anónima. Agora envie uma mensagem real.

curl -H "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN" \
  -H "Title: Nightly backup finished" \
  -H "Priority: default" \
  -H "Tags: white_check_mark" \
  -d "42 GB copied in 11 minutes" \
  https://ntfy.example.com/alerts

O servidor responde com a mensagem armazenada em JSON. Assim, sabe que a mensagem foi aceite e não descartada. Title é a primeira linha em negrito. Priority vai de 1 a 5 ou, por nome, de min a urgent, e determina se o telemóvel emite um som. Tags tornam-se emojis na notificação quando o nome corresponde a um código curto de emoji conhecido e permanecem como texto simples quando não corresponde.

Para monitorizar um tópico a partir de um terminal, transmita-o continuamente:

curl -s -u admin https://ntfy.example.com/alerts/raw

curl pede a palavra-passe. Cada mensagem chega numa única linha, e as linhas vazias que aparecem ocasionalmente são keepalives. Abrir https://ntfy.example.com num navegador e iniciar sessão com a mesma conta apresenta a versão web da mesma transmissão.

Defina limites de taxa para que um script não possa inundar o servidor

Por predefinição, cada visitante recebe um balde de 60 pedidos, reabastecido à razão de um pedido a cada 5 segundos. Isto é generoso para um servidor privado, e um script preso num ciclo de novas tentativas vai consumir todo o limite. Adicione limites a server.yml.

visitor-request-limit-burst: 30
visitor-request-limit-replenish: "10s"
visitor-message-daily-limit: 500

sudo docker compose restart ntfy

Um visitante que exceda o limite recebe HTTP 429 em vez de uma mensagem entregue. O limite é contado por endereço do visitante. Por isso, behind-proxy: true é tão importante: sem essa configuração, o ntfy vê apenas o endereço do Caddy, todos os clientes contam como o mesmo visitante, e um script ruidoso esgota o balde partilhado pelo seu telefone e pelos outros servidores.

Alerta de um cron job que falha

Mantenha o token fora da linha de comandos. ps aux mostra a linha de comandos completa de todos os processos em execução a todos os utilizadores do sistema, por isso um token passado com -H fica legível para qualquer conta local enquanto o curl estiver em execução. Um ficheiro de configuração do curl evita isso.

sudo install -d -m 700 /etc/ntfy-alert
printf 'header = "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN"\n' | sudo tee /etc/ntfy-alert/curlrc
sudo chmod 600 /etc/ntfy-alert/curlrc

Agora envolva o job num script. Guarde-o como /usr/local/bin/backup-with-alert.sh e torne-o executável com chmod 750.

#!/bin/bash
out=$(/usr/local/bin/backup.sh 2>&1)
code=$?
if [ "$code" -ne 0 ]; then
  printf '%s' "$out" | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
    -H "Title: backup.sh failed with exit $code" \
    -H "Priority: high" \
    -H "Tags: warning" \
    --data-binary @- \
    https://ntfy.example.com/alerts
fi
exit "$code"

17 3 * * * /usr/local/bin/backup-with-alert.sh >> /var/log/backup-alert.log 2>&1

$? é capturado na linha imediatamente após o comando, porque a execução do comando seguinte iria substituí-lo. A saída passa por tail -c 1000 porque o ntfy impõe um tamanho máximo para as mensagens e uma notificação não é um visualizador de logs. O exit "$code" de fecho preserva o estado original, para que qualquer outro mecanismo que monitorize este job continue a detetar uma falha. Teste tudo apontando o script para /bin/false numa execução.

Um ramo de falha que nunca é executado é pior do que não ter alertas, porque dá a entender que o silêncio significa sucesso. O cron fornece ao job um ambiente quase vazio e um PATH muito mais curto do que o da sua shell de login, por isso um script que funciona quando é executado manualmente pode terminar antes de chegar à linha do curl. O guia sobre as causas de um cron job não ser executado explica essas armadilhas relacionadas com o ambiente. Utilize caminhos absolutos em todo o lado e leia o ficheiro de log depois da primeira execução agendada, em vez de assumir que tudo funcionou.

Alertar quando uma unidade systemd falha

O cron cobre tarefas agendadas. Serviços de longa duração precisam de OnFailure=, que o systemd executa sempre que uma unidade entra no estado failed. Crie uma unidade de modelo e reutilize-a para todos os serviços do servidor. Guarde-a como /etc/systemd/system/ntfy-unit-failed@.service.

[Unit]
Description=Send an ntfy alert because %i failed

[Service]
Type=oneshot
ExecStart=/usr/local/bin/ntfy-unit-failed %i

Em seguida, /usr/local/bin/ntfy-unit-failed, com o modo 750:

#!/bin/bash
unit="$1"
journalctl -u "$unit" -n 15 --no-pager -o cat | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
  -H "Title: $unit failed on $(hostname -s)" \
  -H "Priority: urgent" \
  -H "Tags: rotating_light" \
  --data-binary @- \
  https://ntfy.example.com/alerts

Associe-a a um serviço com um drop-in, para que uma atualização do pacote não substitua a sua edição.

sudo systemctl edit myapp.service

[Unit]
OnFailure=ntfy-unit-failed@%n.service

%n é expandido para o nome completo da unidade, por isso a instância passa a ser ntfy-unit-failed@myapp.service, e %i dentro do modelo passa myapp.service ao script como primeiro argumento. É isso que permite usar um único modelo para todas as unidades. Confirme que funciona com uma unidade que falha de propósito, guardada como /etc/systemd/system/ntfy-selftest.service.

[Unit]
Description=Deliberately failing unit
OnFailure=ntfy-unit-failed@%n.service

[Service]
Type=oneshot
ExecStart=/bin/false

sudo systemctl daemon-reload
sudo systemctl start ntfy-selftest.service

O comando de arranque termina com um código diferente de zero e imprime Job for ntfy-selftest.service failed because the control process exited with error code, e o telefone deverá emitir um alerta cerca de um segundo depois. Elimine a unidade de teste no fim.

Há uma armadilha importante. OnFailure= só é executado quando uma unidade atinge o estado failed, e um serviço com Restart=always pode nunca o atingir, porque o systemd continua a reiniciá-lo. A unidade só falha depois de exceder StartLimitBurst reinícios dentro de StartLimitIntervalSec. Defina esses dois valores em qualquer serviço sobre o qual queira receber alertas; caso contrário, um ciclo de falhas e reinícios pode continuar silenciosamente durante dias. Os timers são a alternativa mais adequada ao padrão baseado em cron acima, porque a unidade de serviço de um timer recebe OnFailure= automaticamente, e o guia sobre serviços e timers systemd numa VPS mostra como converter um deles.

Configure um monitor de disponibilidade no mesmo tópico

Uptime Kuma, o monitor de estado alojado localmente, inclui um tipo de notificação ntfy. Abra Settings, depois Notifications e, em seguida, Setup Notification. Escolha Ntfy, defina o URL do servidor como https://ntfy.example.com e o tópico como alerts, selecione uma prioridade e cole o token de acesso robot. Envie a notificação de teste antes de guardar, porque um nome de tópico incorreto falha silenciosamente com uma autorização write que não o abrange.

O limite desta configuração é claro: um monitor executado no mesmo VPS não consegue indicar que o VPS está indisponível, e o ntfy não consegue entregar a notificação de que o ntfy está indisponível. Execute o monitor noutra máquina e atribua-lhe um segundo canal de notificação, como o email, para o monitor que acompanha o próprio ntfy. O tipo de monitor Push do Uptime Kuma cobre o outro ponto cego: o seu cron job chama um URL de push depois de uma execução bem-sucedida, e o Kuma gera um alerta quando essas chamadas deixam de chegar. Um ramo de falha é acionado apenas quando o job é executado, por isso não fornece informação sobre um job que nunca foi iniciado.

O ntfy auto-hospedado funciona no Android e no iPhone?

No Android, sim, sem limitações. Instale a aplicação a partir do Google Play ou do F-Droid, abra Settings, defina o servidor predefinido como https://ntfy.example.com, adicione a sua conta no ecrã de gestão de utilizadores e subscreva alerts. A entrega instantânea mantém um serviço em primeiro plano em execução, para que as mensagens cheguem mesmo quando o telefone está no modo doze. A notificação permanente associada é um requisito do Android para serviços em primeiro plano, não um erro. A compilação do F-Droid não contém código Firebase, pelo que todas as subscrições usam a entrega instantânea. O ntfy também pode funcionar como distribuidor UnifiedPush, uma alternativa aberta ao serviço de notificações push da Google. Assim, outras aplicações compatíveis com UnifiedPush também podem entregar notificações através do seu servidor.

No iOS, funciona com uma dependência que não pode remover. A Apple só reativa uma aplicação em segundo plano através do APNs (Apple push notification service). Além disso, apenas a entidade que possui as credenciais de assinatura da aplicação pode enviar notificações para ela. Por isso, o seu servidor não consegue contactar diretamente a aplicação. O ntfy resolve isto através de um relay: o seu servidor envia um poll_request com o ID da mensagem para ntfy.sh. O ntfy.sh encaminha-o através do Firebase e do APNs para reativar a aplicação. Em seguida, a aplicação obtém o corpo da mensagem a partir do seu servidor.

upstream-base-url: "https://ntfy.sh"

Seja claro sobre o custo desta solução. O conteúdo da mensagem permanece no seu servidor, mas o facto de uma mensagem ter chegado e o respetivo ID passam por uma infraestrutura que não controla. Sem esta configuração, as notificações no iPhone provenientes de um servidor auto-hospedado chegam atrasadas ou não chegam, porque nada reativa a aplicação. A única forma de remover o relay é compilar e distribuir a aplicação iOS com a sua própria conta de programador Apple e as suas próprias chaves APNs. Isto implica uma taxa anual e uma nova compilação para cada atualização. Se o relay não for aceitável no seu caso, mantenha os alertas no Android ou na aplicação web para desktop.

Backups, upgrades e fixação da imagem

Não é possível regenerar dois caminhos: /etc/ntfy/server.yml e /var/lib/ntfy/user.db. O segundo contém todos os utilizadores, hashes de palavras-passe, entradas de ACL e tokens, por isso trate-o como uma chave privada.

sudo tar czf ntfy-backup.tgz -C / etc/ntfy var/lib/ntfy
sudo chmod 600 ntfy-backup.tgz

Copie esse ficheiro para fora do servidor. cache.db contém apenas mensagens recentes, correspondentes a 12 horas com o cache-duration acima, por isso a sua perda não elimina nada que valha a pena proteger. Para atualizar, edite a tag no ficheiro compose e faça o pull.

sudo docker compose pull
sudo docker compose up -d
curl -s https://ntfy.example.com/v1/health

Leia primeiro as notas da versão. As bases de dados SQLite são migradas no arranque, por isso não é seguro reverter para uma tag mais antiga depois de uma alteração do esquema. Mantenha a cópia de segurança que acabou de criar até a nova versão estar em execução há um dia. Cada serviço no servidor tem a sua própria lista curta de caminhos que não podem ser regenerados, e a comparação entre PhotoPrism e Immich identifica essa lista e os comandos de backup correspondentes para uma biblioteca de fotografias no mesmo tipo de VPS.

Gotify e Apprise

Gotify é a opção mais pequena: um único binário com uma interface Web e uma aplicação Android, sem curingas de tópicos e sem cliente oficial para iOS. É adequado para um servidor privado em que o Android é o único destino. Apprise é uma biblioteca Python e uma ferramenta de linha de comandos, não um servidor. Distribui uma única mensagem por mais de uma centena de serviços, incluindo ntfy. É adequado para um script que tem de enviar a mensagem para vários destinos em simultâneo. ntfy é a opção que fornece um servidor, uma API HTTP e aplicações para as duas plataformas móveis. Por isso, é a resposta habitual para alertas enviados a partir de um servidor alugado.

FAQ

Por que a publicação no meu servidor ntfy retorna 403?

Com auth-default-access: "deny-all" em server.yml, uma publicação anónima é recusada. Esse é o comportamento esperado. Envie as credenciais com -u user:pass ou -H "Authorization: Bearer tk_...". Se já estiver a enviar um token e continuar a receber 403, o utilizador associado a esse token não tem uma entrada ACL correspondente ao tópico. Execute ntfy access para apresentar a lista completa. Lembre-se de que uma concessão write não permite subscrever. Por isso, uma conta que publica corretamente continuará a ser recusada quando tentar ler o mesmo tópico.

As notificações funcionam no iPhone com um servidor ntfy autoalojado?

Funcionam, através de um relay que não pode evitar. A Apple acorda as aplicações apenas através do APNs (Apple push notification service), e apenas o publicador da aplicação pode enviar para esse serviço. Por isso, o ntfy encaminha para ntfy.sh um poll_request que contém o ID da mensagem, e o ntfy.sh retransmite-o para o dispositivo. Defina upstream-base-url: "https://ntfy.sh" em server.yml e reinicie o contentor. O corpo da mensagem continua a ser obtido a partir do seu servidor. Sem essa definição, as notificações do iOS atrasam-se ou nunca aparecem.

Por que o alerta ntfy do meu cron nunca chegou?

Execute primeiro a linha do curl isoladamente para confirmar que o token e o tópico estão corretos. Se funcionar manualmente, mas não a partir do cron, a falha ocorre antes do alerta: o cron executa os trabalhos com um ambiente mínimo e um PATH curto. Por isso, um script que chama um comando apenas pelo nome pode terminar antes de chegar à linha do curl. Use caminhos absolutos, redirecione a saída do trabalho para um ficheiro de log e leia esse ficheiro depois da execução seguinte. Uma resposta 429, em vez de uma entrega, significa que o limite de taxa está a funcionar e que o script está a repetir as tentativas demasiado depressa.

Devo expor o ntfy na Internet pública?

As aplicações para telemóvel precisam de lhe aceder através de redes móveis. Por isso, um endpoint HTTPS público com auth-default-access: "deny-all" e ACLs por tópico é a configuração normal. É segura desde que nenhum tópico possa ser lido por everyone. Uma instância acessível apenas por VPN é adequada quando todos os subscritores são máquinas que controla. É pouco adequada para telemóveis, porque a aplicação só recebe notificações enquanto o túnel está ativo. Assim, os alertas ficam em fila até o telemóvel voltar a ligar-se.