Alojar ntfy num VPS gerido é enviar notificações push com um simples pedido HTTP, PUT ou POST, a partir de uma máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O ntfy é um software livre com dupla licença, Apache 2.0 e GPLv2. Este guia segue a sua documentação oficial na versão 2.38.1: a instalação com o Docker Compose, o ficheiro server.yml, os utilizadores e o controlo de acesso, os tokens de acesso, o HTTPS, as aplicações móveis, o e-mail, as cópias de segurança e as atualizações.
Por Simon Vasconcelos Lee
Publicado a 21 de novembro de 2026Leitura: 15 minutos
binwiederhier/ntfy, um server.yml com base-url, cache-file e auth-file, e a porta publicada em 127.0.0.1 atrás de um proxy inverso em HTTPS.auth-default-access: deny-all, crie um administrador com ntfy user add e dê depois a cada script o seu próprio token e permissões limitadas.server.yml e de user.db, que guardam a configuração, os utilizadores, as permissões e os tokens; atualize mudando a etiqueta da imagem, depois de ler as notas de versão.O ntfy, que se pronuncia como «notify», é um serviço de notificações de publicação e subscrição baseado em HTTP. O seu README apresenta-o como uma forma de enviar notificações para o seu telemóvel ou computador a partir de scripts, de qualquer máquina. O projeto mantém uma instância pública, ntfy.sh, e o servidor pode ser autoalojado: é disso que trata este guia.
curl, de um script, de uma tarefa agendada ou de outra aplicação. Uma mensagem pode ter um título, uma prioridade de 1 a 5, etiquetas e emojis, um anexo, botões de ação ou uma hora de entrega diferida.ntfy ou a API, por WebSocket ou por um fluxo HTTP que se mantém aberto.curl -d "Backup finished" https://ntfy.example.com/backups
O README do ntfy indica que o projeto tem dupla licença: a Apache License 2.0, no ficheiro LICENSE, e a GNU GPL versão 2, em LICENSE.GPLv2. A imagem Docker declara ambas, Apache-2.0, GPL-2.0.
Fazer correr o ntfy no seu servidor, para a sua empresa, a sua equipa ou os seus clientes, não exige, portanto, nenhuma licença para comprar. Os dois textos fornecem o software sem garantia.
A licença cobre o código. O nome é outra questão: a Apache License 2.0 não concede nenhum direito sobre as marcas do licenciante, e os termos de serviço do ntfy.sh indicam que o nome, o logótipo e a identidade visual do ntfy são marcas da ntfy LLC, cuja utilização em ligação com um produto ou um serviço exige o seu consentimento prévio por escrito. Este guia nomeia o ntfy para descrever o software.
Esta publicação é independente do projeto ntfy e da ntfy LLC, e não é afiliada, patrocinada nem aprovada por eles.
O servidor é um único binário ligado estaticamente, para amd64, armv7 e arm64; a imagem Docker existe também para armv6. A documentação não dá nenhum valor de memória nem de processador: para um servidor doméstico, diz, a escala não é motivo de preocupação. Aponta, em contrapartida, o que limita uma instância:
nofile, permite. O serviço systemd do pacote fixa-o em 10 000.Num VPS gerido, descreva-nos a sua utilização, o número de dispositivos subscritos, o volume de mensagens e os anexos, e recomendamos-lhe o tamanho adequado.
A documentação propõe a imagem binwiederhier/ntfy no Docker Hub. Serve a aplicação web e a API na porta 80 do contentor, e não contém nenhum ficheiro server.yml: a configuração fica numa pasta montada em /etc/ntfy. Num servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, baseado no exemplo da documentação:
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
Depois, o ficheiro de configuração, em etc/server.yml, com o endereço público do seu servidor:
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
O servidor responde {"healthy":true,"role":"active"}. O que faz cada definição:
127.0.0.1:2586: os exemplos Docker da documentação publicam a porta 80 em todos os endereços, e os seus exemplos de proxy inverso encaminham para 127.0.0.1:2586. Publicada assim, a porta só é acessível a partir do próprio servidor, e a API é alcançada apenas através do proxy inverso, em HTTPS.base-url: o endereço público do serviço. O ficheiro server.yml de exemplo exige-o para os anexos, o envio de e-mails e as notificações iOS a partir de um servidor autoalojado.cache-file: sem ele, as mensagens ficam em memória durante 12 horas e perdem-se ao reiniciar. Esta cache permite aos telemóveis com uma ligação instável recuperar as mensagens que perderam.attachment-cache-dir: ativa os anexos. O ntfy assume o controlo total desta pasta, por isso reserve-a para este uso.auth-file e auth-default-access: deny-all: a base de dados de utilizadores e permissões, criada no primeiro arranque, e o acesso anónimo recusado por predefinição. É a definição que a documentação recomenda para uma instância privada.behind-proxy: sem ele, atrás de um proxy, todos os visitantes partilham o endereço IP do proxy e os mesmos limites de débito.enable-login: permite iniciar sessão na aplicação web. O registo aberto mantém-se fechado, porque enable-signup vale false por predefinição.v2.38.1 fixa a versão; latest acompanha a versão mais recente. A documentação propõe também user: UID:GID para uma conta que não seja root: os ficheiros de etc e lib passam então a pertencer-lhe.O projeto publica também um repositório de pacotes, assinado com a chave de impressão digital 55BA 774A 6F5E E674 31E4 B6B7 CFDB 962D 4F1E C4AF. Num servidor 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
O pacote lê /etc/ntfy/server.yml. O ficheiro de exemplo recomenda /var/cache/ntfy/cache.db para a cache e /var/lib/ntfy/user.db para os utilizadores, duas pastas que o pacote cria. Atrás de um proxy, acrescente listen-http: "127.0.0.1:2586".
De origem, um servidor ntfy está aberto: qualquer pessoa pode ler e escrever em todos os tópicos, e o nome do tópico serve de palavra-passe. Com auth-file e deny-all, nada passa sem credenciais. O ntfy tem duas funções: admin, que lê e escreve em todos os tópicos, e user, que só tem as permissões que lhe conceder.
docker compose exec ntfy ntfy user add --role=admin alice
O comando pede a palavra-passe e depois a sua confirmação. Os comandos ntfy user, ntfy access e ntfy token escrevem diretamente na base de dados de utilizadores: correm no servidor, aqui dentro do contentor, que lê o caminho dessa base em server.yml.
De momento, um token de acesso dá acesso total à conta do seu utilizador, exceto para mudar a palavra-passe e eliminar a conta. Para um script, crie um utilizador dedicado, limitado aos seus tópicos, e depois um token para ele:
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 ou deny, sobre um tópico preciso ou sobre um padrão como alerts-*, o único caráter universal suportado.everyone, ou *. Para o UnifiedPush numa instância privada, a documentação abre apenas em escrita os tópicos que começam por up: ntfy access '*' 'up*' write-only.tk_, podem expirar com --expires=30d, e cada utilizador pode manter até 60. ntfy token list mostra-os, ntfy token remove elimina um.auth-users, auth-access e auth-tokens criam os mesmos objetos a partir de server.yml, em cada arranque. Um utilizador retirado dessa lista é eliminado da base no reinício seguinte.O script publica depois com o seu token, em 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
Uma palavra-passe em Basic auth está apenas codificada em base64, não cifrada: a documentação pede HTTPS em todos os servidores autoalojados. É o que trata a secção seguinte.
O ntfy pode servir HTTPS ele próprio, mas atrás de um proxy a documentação recomenda deixar a terminação TLS ao proxy. Há dois pontos que contam mais do que tudo o resto:
Upgrade e Connection, e deixa viver estas ligações longas. O ntfy envia por predefinição uma mensagem keepalive a cada 45 segundos, keepalive-interval, para que nenhum intermediário as feche por inatividade.behind-proxy: true, o ntfy lê o cabeçalho X-Forwarded-For e fica com o endereço mais à direita, o que o seu proxy acrescenta. Os limites de débito aplicam-se a esse endereço.A documentação assinala que o Caddy trata ao mesmo tempo o HTTP e o WebSocket com reverse_proxy, sem nenhuma definição adicional. Obtém sozinho o certificado Let’s Encrypt:
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}
Este bloco segue a configuração da documentação, próxima da que o ntfy.sh utiliza: buffering desativado para os fluxos, tempos limite de 3 minutos e nenhum limite de tamanho no corpo dos pedidos, que o próprio ntfy limita. Escuta na porta 80 para deixar o Certbot instalar o 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
Quando o HTTP redirecionar para HTTPS, publique para endereços https:// nos seus scripts. Para milhares de subscritores, a documentação aumenta worker_connections em nginx.conf e o LimitNOFILE do serviço Nginx, para o dobro das ligações pretendidas.
As aplicações ntfy acrescentam os tópicos do seu servidor tal como os do ntfy.sh: introduza o respetivo endereço ao acrescentar o tópico e, para um tópico protegido, o nome de utilizador e a palavra-passe de um utilizador que lhe tenha acesso. A aplicação web é servida no próprio endereço do servidor.
ntfy webpush keys e de um certificado HTTPS válido.Acrescente uma linha a server.yml e reinicie depois o contentor:
upstream-base-url: "https://ntfy.sh"
Para cada mensagem, o seu servidor publica então no ntfy.sh um pedido de consulta, que contém apenas o identificador da mensagem e o hash SHA-256 do URL do tópico. O ntfy.sh transmite-o ao dispositivo através do serviço de notificações da Apple, e a aplicação vai depois buscar a mensagem ao seu servidor. O texto que passa pelo ntfy.sh é sempre o mesmo, «New message», diga o seu o que disser. Sem esta definição, as notificações chegam na mesma, com um atraso que pode chegar a várias horas consoante o estado do telemóvel. upstream-access-token acrescenta um token se ultrapassar os limites de débito do ntfy.sh.
O ntfy limita cada visitante, identificado pelo seu endereço IP e, em IPv6, pela sua sub-rede /64. Estes limites protegem o servidor dos abusos; numa utilização normal, diz a documentação, não deverá atingi-los. Para além deles, o servidor responde 429 Too Many Requests. Os valores predefinidos:
| Definição | Predefinição | O que limita |
|---|---|---|
visitor-request-limit-burst | 60 | Os pedidos de um visitante numa rajada |
visitor-request-limit-replenish | 5s | O ritmo de recarga: um pedido a cada 5 segundos |
visitor-subscription-limit | 30 | As ligações abertas por visitante |
visitor-message-daily-limit | Nenhum | As mensagens por dia, reguladas de outro modo pelo limite de pedidos |
visitor-email-limit-burst | 16 | Os e-mails numa rajada, e depois um por hora |
visitor-attachment-total-size-limit | 100M | O armazenamento de anexos por visitante |
visitor-attachment-daily-bandwidth-limit | 500M | O tráfego de anexos por visitante e por dia |
global-topic-limit | 15 000 | O número total de tópicos do servidor |
message-size-limit | 4K | O tamanho de uma mensagem; acima dele, passa a anexo |
visitor-request-limit-exempt-hosts, uma lista de endereços IP ou de nomes de anfitrião.ntfy tier, dão a algumas contas limites mais elevados.attachment-file-size-limit, 15M por predefinição, limita cada ficheiro, attachment-total-size-limit, 5G, o armazenamento total, e attachment-expiry-duration, 3h, a sua duração. Um anexo nunca dura mais do que a sua mensagem: para guardar os anexos mais tempo, aumente também cache-duration.O ntfy pode reencaminhar uma mensagem por e-mail quando o pedido de publicação traz o cabeçalho Email, ou X-Email, com um endereço. Para isso passa por um servidor SMTP de saída, em STARTTLS, com autenticação PLAIN ou LOGIN: é a porta 587. A partir de um VPS Simafri, o e-mail sai por um relé SMTP autenticado nessa mesma porta 587: configure aqui o endereço de uma conta de e-mail que já tenha, ou o do seu serviço de envio de e-mails.
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 são obrigatórios a partir do momento em que smtp-sender-addr está definido: sem eles, o servidor recusa-se a arrancar.smtp-sender-verify: true limita o envio aos endereços que cada utilizador verificou na sua conta, e fecha-o aos utilizadores anónimos.server.yml: mantenha esse ficheiro legível apenas pelo seu proprietário, com chmod 600.Com o SQLite, o ntfy guarda cada tipo de dados no seu próprio ficheiro. Na instalação deste guia, tudo fica nas pastas etc e lib, ao lado do compose.yaml:
| Elemento | O que guarda | Copiar |
|---|---|---|
etc/server.yml | A configuração, incluindo os segredos SMTP e as chaves Web Push | Sim |
lib/user.db | Os utilizadores, as entradas de controlo de acesso, os tokens e os contadores diários | Sim |
lib/cache.db | As mensagens das últimas 12 horas, por predefinição | Útil, a sua duração é curta |
lib/attachments/ | Os anexos das últimas 3 horas, por predefinição | Útil, a sua duração é curta |
Ficheiro web-push-file | As subscrições Web Push dos navegadores, se o tiver ativado | Sim |
Para uma cópia coerente dos ficheiros SQLite, pare o serviço enquanto o arquivo é criado:
docker compose stop
tar -czf ntfy-$(date +%F).tar.gz compose.yaml etc lib
docker compose start
Agende esta cópia para uma hora calma e envie-a para fora do servidor. Colocados no seu disco, estes arquivos entram também nas suas cópias de segurança noturnas. Para restaurar, volte a pôr as pastas no lugar e execute depois docker compose up -d.
Se perder user.db sem nenhuma cópia, os utilizadores e os tokens declarados em server.yml através de auth-users e auth-tokens são recriados no arranque; os que foram criados na linha de comandos têm de ser criados de novo.
Com o Docker, mude a etiqueta da imagem em compose.yaml, por exemplo de v2.38.1 para a versão seguinte, e depois:
docker compose pull
docker compose up -d
As pastas etc e lib mantêm-se no lugar, e o ntfy migra ele próprio as suas bases de dados no arranque. Com o pacote Debian, sudo apt update e depois sudo apt upgrade fazem o mesmo.
As notas de cada versão, na página «Releases» da documentação, reúnem em «Upgrade notes» o que muda para uma instância existente, como, na 2.36.0, uma configuração agora verificada por inteiro no arranque, ou os contadores diários repostos a zero. Leia-as antes de atualizar e copie as duas pastas logo antes. A versão 2.38.1 é uma versão de segurança, que o projeto recomenda vivamente: reforça os modelos de mensagens contra ataques de negação de serviço e impede que carregamentos lentos de anexos para o S3 e pontos de terminação web push que deixaram de responder ocupem memória e ligações. Sucede à 2.38.0, que partilha os limites de débito entre os nós de um cluster e é compilada com o Go 1.27.4.
O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o ntfy continua a ser o seu software, com as suas definições e os seus dados.
| Assunto | As nossas equipas | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, intervenções no servidor incluídas | O momento que convém à sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamada | A leitura dos registos da sua instância |
| ntfy | Acompanhamento proativo: erros, lentidão, ligações abertas e espaço em disco identificados, correção recomendada | A sua instalação, as suas atualizações e as suas definições, que aplica diretamente ou com o seu assistente de IA |
| Os acessos | O servidor que o suporta, vigiado e com cópias de segurança | Os utilizadores, as permissões dos tópicos e os tokens dos seus scripts |
| As cópias de segurança | Todas as noites, cifradas e guardadas fora da máquina; restauro incluído | As cópias próprias do ntfy e o pedido de restauro, quando precisar |
| A migração | O seu servidor atual migrado, oferecido | O momento da mudança |
Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.
Com um VPS gerido da Simafri, as nossas equipas mantêm atualizado o servidor da sua instância ntfy, vigiam-no dia e noite e intervêm sem esperar pela sua chamada; acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica diretamente ou com o seu assistente de IA. As cópias de segurança são cifradas todas as noites e guardadas fora da máquina, o seu restauro está incluído, e a migração do seu servidor atual é oferecida.
Sim. O ntfy tem dupla licença, Apache 2.0 e GPLv2: pode fazê-lo correr numa empresa sem licença para comprar. As suas condições aplicam-se à redistribuição do software. Resta o custo do servidor que o faz funcionar.
Crie um compose.yaml com a imagem binwiederhier/ntfy, o comando serve, uma pasta montada em /etc/ntfy para o server.yml, outra em /var/lib/ntfy para as bases de dados, e a porta 80 do contentor publicada em 127.0.0.1:2586. Execute docker compose up -d e coloque depois um proxy inverso em HTTPS à frente dessa porta.
Em server.yml, defina auth-file e auth-default-access: deny-all. Crie depois um administrador com ntfy user add --role=admin, utilizadores limitados com ntfy user add, e as respetivas permissões sobre os tópicos com ntfy access.
Crie um token com ntfy token add para um utilizador dedicado ao script, limitado aos seus tópicos, e publique depois com o curl e o cabeçalho Authorization: Bearer seguido do token, em HTTPS. Um token dá acesso a toda a conta do seu utilizador.
Atrás de um proxy inverso, todos os pedidos vêm do endereço do proxy. Com behind-proxy: true, o ntfy lê o cabeçalho X-Forwarded-For para identificar cada visitante; sem ele, todos partilham os mesmos limites de débito.
Sim, com upstream-base-url: "https://ntfy.sh" em server.yml. O seu servidor faz então retransmitir pelo ntfy.sh um sinal que contém apenas o identificador da mensagem, e a aplicação vai buscar a mensagem ao seu servidor. Sem esta definição, a entrega pode demorar várias horas.
Copie server.yml e user.db, que guardam a configuração, os utilizadores, as permissões e os tokens, bem como o ficheiro Web Push se estiver ativado. A cache de mensagens e os anexos têm uma duração curta. Pare o serviço durante a cópia, para obter ficheiros SQLite coerentes.
Um VPS gerido cobre o servidor: sistema, segurança, supervisão e cópias de segurança. As nossas equipas acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica. Uma intervenção na aplicação é faturada à hora ou por pacote.
Simafri
Vamos falar do seu projeto
Diga-nos em poucas palavras o que precisa: respondemos-lhe rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o email? Escreva-nos para support@simafri.com.