Como fazer self-hosting do ntfy em 2026: tópicos, controle de acesso e entrega

A maioria das instruções de instalação do ntfy termina no primeiro carregamento da página. Isso é cedo demais: o cache é efêmero ou as conexões WebSocket/SSE expiram no proxy. Um teste de produção útil é mais exigente: publicar uma mensagem com curl, recebê-la por meio de subscriptions HTTP e WebSocket, anexar um arquivo e testar um tópico autenticado.

O papel do ntfy é simples: enviar notificações push com uma requisição HTTP simples. Seus limites operacionais vão além do processo web, portanto a dependência, o estado armazenado e a rota pública precisam ser especificados antes que dados reais cheguem.

A estrutura do ntfy em produção

O processo HTTP do ntfy escuta na porta 80; mantenha essa porta na rede da aplicação e publique apenas a rota da plataforma. O requisito do runtime local é um volume de configuração e, opcionalmente, um banco de dados de autenticação. Teste esse limite antes da publicação e novamente após substituir o container.

Registre esse limite como um contrato curto: quem é responsável pelo requisito, qual credencial é usada, qual timeout é aceitável e como a falha se manifesta. Em seguida, execute esta transação: publique uma mensagem com curl, receba-a por meio de subscriptions HTTP e WebSocket, anexe um arquivo e teste um tópico autenticado. Durante a execução, observe as conexões de subscribers de longa duração, o tamanho dos anexos, a retenção do cache e os relays de push de saída, pois essa carga oferece um ponto de partida mais útil para dimensionamento do que um container ocioso.

Inicie o ntfy sem ocultar as partes móveis

Use o container como um runtime substituível, não como a fonte da verdade.

docker run -d \
  --name ntfy \
  --restart unless-stopped \
  -p 127.0.0.1:80:80 \
  -v ntfy-data:/var/cache/ntfy \
  -e NTFY_BASE_URL=https://app.example.com \
  binwiederhier/ntfy:latest serve

Confirme o requisito local antes da exposição: um volume de configuração e, opcionalmente, um banco de dados de autenticação. Inspecione o usuário do container, os caminhos com permissão de escrita e a porta em escuta antes de expô-lo. Execute a ação completa — publique uma mensagem com curl, receba-a por meio de subscriptions HTTP e WebSocket, anexe um arquivo e teste um tópico autenticado — e salve a referência exata da imagem que produziu o resultado.

Dê ao ntfy um endereço canônico

Defina base-url como a origem HTTPS pública usada por publishers e subscribers. Encaminhe o hostname escolhido para a porta 80 do container, encaminhe o host original e o esquema HTTPS e evite publicar uma segunda origem direta.

Teste o ntfy a partir de um client externo limpo. Separe falhas de ingress do limite conhecido da aplicação — o cache é efêmero ou as conexões WebSocket/SSE expiram no proxy. Um erro de certificado, DNS ou 502 pertence ao roteamento; uma requisição que chega ao ntfy e falha depois pertence ao estado da aplicação, à capacidade ou ao requisito de suporte. O guia de TLS para domínios personalizados aborda o primeiro grupo.

Comprove que o ntfy sobrevive à substituição

Proteja o estado do ntfy antes de otimizar o container. O conjunto necessário inclui a configuração, o banco de dados de autenticação e os anexos que precisam sobreviver. Monte /var/cache/ntfy antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Se vários stores precisarem permanecer consistentes, documente a ordem em que as gravações são pausadas e os backups são realizados.

Mantenha cópias fora do servidor de deployment e criptografe o material que contenha credenciais ou conteúdo privado. A recuperação é bem-sucedida quando usuários, ACLs, configuração e anexos retidos retornam e um subscriber autenticado recebe uma nova mensagem. A diferença entre um mount persistente e uma cópia independente é abordada em armazenamento persistente e snapshots.

Não dê ao ntfy acesso ao host inteiro

No ntfy, a superfície mais valiosa não é necessariamente a landing page. O principal erro é permitir a enumeração pública de tópicos quando as mensagens contêm detalhes operacionais. Combata isso deliberadamente: use ACLs de tópicos, pois nomes de tópicos difíceis de adivinhar não são uma autorização forte para mensagens operacionais.

NTFY_BASE_URL é uma configuração, não um segredo; mantenha seu valor explícito e proteja as credenciais separadas usadas pelo ntfy. Use um usuário não privilegiado no container quando a imagem oferecer suporte a isso e não monte credenciais que não tenham relação com o serviço. Aplique limites de rate ou tamanho no ingress, onde trabalho não confiável pode consumir conexões de subscribers de longa duração, tamanho dos anexos, retenção do cache e relays de push de saída.

Atualize o ntfy sem fazer suposições

Use publicar uma mensagem com curl, recebê-la por meio de subscriptions HTTP e WebSocket, anexar um arquivo e testar um tópico autenticado como smoke test do ntfy após cada deployment. Suas métricas de suporte são conexões de subscribers de longa duração, tamanho dos anexos, retenção do cache e relays de push de saída; gere alertas quando esses recursos se aproximarem de um ponto que degrade a ação do usuário.

O principal risco de mudança é que as chaves de configuração, as migrações do banco de dados de autenticação e as expectativas dos clients devem ser verificadas antes da atualização do ntfy. Um release seguro começa com um snapshot restaurável e valida qualquer alteração de estado irreversível antes de mover o tráfego. Quando o cache é efêmero ou as conexões WebSocket/SSE expiram no proxy, mantenha o container com falha tempo suficiente para ler sua configuração e o primeiro erro.

O gate de release do ntfy

Um release candidate do ntfy ganha tráfego ao concluir um cenário fixo: publicar uma mensagem com curl, recebê-la por meio de subscriptions HTTP e WebSocket, anexar um arquivo e testar um tópico autenticado. Registre o digest da imagem, a configuração efetiva não secreta, a origem pública e os timestamps desse cenário. Os dados de teste devem ser descartáveis, mas realistas o suficiente para exercitar o mesmo caminho usado pelos usuários.

Execute o cenário após substituir o runtime e, em seguida, recrie o serviço a partir da configuração, do banco de dados de autenticação e dos anexos que precisam sobreviver. A recuperação é aprovada quando usuários, ACLs, configuração e anexos retidos retornam e um subscriber autenticado recebe uma nova mensagem. Compare as medições de recursos — conexões de subscribers de longa duração, tamanho dos anexos, retenção do cache e relays de push de saída — com o release anterior e investigue qualquer variação significativa antes da promoção.

Por fim, exercite esta falha controlada: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a este limite: o cache é efêmero ou as conexões WebSocket/SSE expiram no proxy. Verifique se o ntfy explica a falha, não danifica o estado existente e retoma a operação quando a condição válida retorna. Salve um trecho de log com dados sensíveis removidos e o tempo de recuperação. Juntos, esses testes cobrem comportamento, durabilidade e operabilidade, em vez de apenas a disponibilidade do processo.

Mantenha o ntfy explícito enquanto o Dockup cuida do roteamento

Roteamento, certificados, substituição do serviço e armazenamento anexado são alvos razoáveis para automação. O Dockup cuida disso para o ntfy e pode provisionar o banco de dados gerenciado relacionado ou conectar-se a serviços no servidor do próprio cliente.

O que ele não deve inventar é a trust policy do ntfy. Após o deployment, defina base-url como a origem HTTPS pública usada por publishers e subscribers, aplique este limite — use ACLs de tópicos, pois nomes de tópicos difíceis de adivinhar não são uma autorização forte para mensagens operacionais — e verifique o resultado deste cenário: publique uma mensagem com curl, receba-a por meio de subscriptions HTTP e WebSocket, anexe um arquivo e teste um tópico autenticado. O resultado é uma infraestrutura de um clique com um acceptance test específico da aplicação.

Perguntas frequentes

O que o ntfy precisa para um deployment em produção?

Encaminhe o container do ntfy na porta 80 por meio de uma única origem HTTPS. O requisito do runtime local é um volume de configuração e, opcionalmente, um banco de dados de autenticação. Não considere o ntfy pronto até conseguir publicar uma mensagem com curl, recebê-la por meio de subscriptions HTTP e WebSocket, anexar um arquivo e testar um tópico autenticado.

Quais dados do ntfy devem fazer parte do backup?

Torne /var/cache/ntfy persistente e inclua a configuração, o banco de dados de autenticação e os anexos que precisam sobreviver no mesmo recovery manifest. Um restore limpo do ntfy só é aprovado quando usuários, ACLs, configuração e anexos retidos retornam e um subscriber autenticado recebe uma nova mensagem.

O ntfy precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do ntfy e mantenha a porta 80 na rota interna. Aplique corretamente a configuração do ntfy: defina base-url como a origem HTTPS pública usada por publishers e subscribers. No ntfy, o HTTPS protege credenciais ou conteúdo dos usuários durante o trânsito e mantém consistente o comportamento dos clients sensível à origem.

Como testar uma atualização do ntfy?

Restaure o estado atual do ntfy em um deployment isolado, aplique a versão candidata e repita sua transação de acceptance. Dê atenção especial ao fato de que as chaves de configuração, as migrações do banco de dados de autenticação e as expectativas dos clients devem ser verificadas antes da atualização do ntfy. Mantenha a imagem anterior do ntfy até compreender os limites de migração de dados e rollback.