Hospedar ntfy em um VPS gerenciado é enviar notificações push com uma simples requisição HTTP, PUT ou POST, a partir de uma máquina própria, que nossas equipes mantêm atualizada e supervisionam dia e noite. O ntfy é um software livre com licença dupla, Apache 2.0 e GPLv2. Este guia segue a documentação oficial dele na versão 2.38.1: a instalação com Docker Compose, o arquivo server.yml, os usuários e o controle de acesso, os tokens de acesso, o HTTPS, os aplicativos móveis, o e-mail, os backups e as atualizações.
Por Simon Vasconcelos Lee
Publicado em 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 reverso em HTTPS.auth-default-access: deny-all, crie um administrador com ntfy user add e depois dê a cada script seu próprio token e permissões limitadas.server.yml e user.db, que guardam a configuração, os usuários, as permissões e os tokens; atualize trocando a tag da imagem, depois de ler as notas de versão.O ntfy, pronunciado como “notify”, é um serviço de notificações de publicação e assinatura baseado em HTTP. O README dele o apresenta como uma forma de enviar notificações para seu celular ou computador a partir de scripts, de qualquer máquina. O projeto mantém uma instância pública, a ntfy.sh, e o servidor pode ser auto-hospedado: é disso que este guia trata.
curl, de um script, de uma tarefa agendada ou de outra aplicação. Uma mensagem pode levar um título, uma prioridade de 1 a 5, tags e emojis, um anexo, botões de ação ou um horário de entrega programado.ntfy ou a API, por WebSocket ou por um fluxo HTTP que fica aberto.curl -d "Backup finished" https://ntfy.example.com/backups
O README do ntfy informa que o projeto tem licença dupla: a Apache License 2.0, no arquivo LICENSE, e a GNU GPL versão 2, em LICENSE.GPLv2. A imagem Docker declara as duas, Apache-2.0, GPL-2.0.
Rodar o ntfy em seu servidor, para sua empresa, sua equipe ou seus clientes, não exige, portanto, nenhuma licença a 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 informam que o nome, o logotipo e a identidade visual do ntfy são marcas da ntfy LLC, cujo uso em conexão com um produto ou um serviço exige o consentimento prévio por escrito dela. Este guia cita 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 com linkagem estática, para amd64, armv7 e arm64; a imagem Docker também existe para armv6. A documentação não informa números de memória nem de CPU: para um servidor doméstico, diz ela, a escala não é motivo de preocupação. Ela aponta, em vez disso, o que limita uma instância:
nofile, permite. O serviço systemd do pacote o define em 10.000.Em um VPS gerenciado, fale-nos de seu uso, do número de dispositivos inscritos, do volume de mensagens e dos anexos, e recomendamos o tamanho adequado.
A documentação propõe a imagem binwiederhier/ntfy do Docker Hub. Ela serve o aplicativo web e a API na porta 80 do contêiner e não traz nenhum arquivo server.yml: a configuração vai em uma pasta montada em /etc/ntfy. Em um servidor com 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 arquivo de configuração, em etc/server.yml, com o endereço público de 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 cada configuração faz:
127.0.0.1:2586: os exemplos Docker da documentação publicam a porta 80 em todos os endereços, e os exemplos de proxy reverso dela encaminham para 127.0.0.1:2586. Publicada assim, a porta só é acessível a partir do próprio servidor, e a API só é alcançada pelo proxy reverso, em HTTPS.base-url: o endereço público do serviço. O arquivo server.yml de exemplo o exige para os anexos, o envio de e-mails e as notificações iOS a partir de um servidor auto-hospedado.cache-file: sem ele, as mensagens ficam na memória por 12 horas e se perdem ao reiniciar. Esse cache permite que celulares com uma conexão instável recuperem as mensagens que perderam.attachment-cache-dir: ativa os anexos. O ntfy assume o controle total dessa pasta, então reserve-a só para esse uso.auth-file e auth-default-access: deny-all: o banco de dados de usuários e permissões, criado na primeira inicialização, e o acesso anônimo negado por padrão. É a configuração que a documentação recomenda para uma instância privada.behind-proxy: sem ele, atrás de um proxy, todos os visitantes compartilham o endereço IP do proxy e os mesmos limites de taxa.enable-login: permite fazer login no aplicativo web. O cadastro aberto continua fechado, já que enable-signup vale false por padrão.v2.38.1 fixa a versão; latest acompanha a versão mais recente. A documentação também propõe user: UID:GID para uma conta que não seja root: os arquivos de etc e lib passam então a pertencer a ela.O projeto também publica um repositório de pacotes, assinado com a chave de impressão digital 55BA 774A 6F5E E674 31E4 B6B7 CFDB 962D 4F1E C4AF. Em um 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 arquivo de exemplo recomenda /var/cache/ntfy/cache.db para o cache e /var/lib/ntfy/user.db para os usuários, duas pastas que o pacote cria. Atrás de um proxy, acrescente listen-http: "127.0.0.1:2586".
Logo de saída, um servidor ntfy é aberto: qualquer pessoa pode ler e escrever em todos os tópicos, e o nome do tópico funciona como senha. Com auth-file e deny-all, nada passa sem credenciais. O ntfy tem dois papéis: admin, que lê e escreve em todos os tópicos, e user, que só tem as permissões que você concede.
docker compose exec ntfy ntfy user add --role=admin alice
O comando pede a senha e depois a confirmação dela. Os comandos ntfy user, ntfy access e ntfy token escrevem direto no banco de dados de usuários: eles rodam no servidor, aqui dentro do contêiner, que lê o caminho desse banco em server.yml.
Por enquanto, um token de acesso dá acesso completo à conta do usuário dele, exceto para mudar a senha e excluir a conta. Para um script, crie um usuário dedicado, limitado aos tópicos dele, 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, em um tópico específico ou em um padrão como alerts-*, o único curinga aceito.everyone, ou *. Para o UnifiedPush em uma instância privada, a documentação abre só para escrita os tópicos que começam com up: ntfy access '*' 'up*' write-only.tk_, podem expirar com --expires=30d, e cada usuário pode manter até 60 deles. ntfy token list os mostra, ntfy token remove exclui um.auth-users, auth-access e auth-tokens criam os mesmos objetos a partir do server.yml, a cada inicialização. Um usuário retirado dessa lista é excluído do banco na reinicialização seguinte.O script publica então com o token dele, 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 senha em Basic auth é apenas codificada em base64, não criptografada: a documentação pede HTTPS em todo servidor auto-hospedado. É o assunto da próxima seção.
O ntfy pode servir HTTPS sozinho, mas atrás de um proxy a documentação recomenda deixar a terminação TLS com o proxy. Dois pontos importam mais que todo o resto:
Upgrade e Connection e deixa essas conexões longas viverem. O ntfy envia por padrã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 seu proxy acrescenta. Os limites de taxa se aplicam a esse endereço.A documentação observa que o Caddy cuida ao mesmo tempo do HTTP e do WebSocket com reverse_proxy, sem nenhuma configuração adicional. Ele 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 a ntfy.sh usa: buffering desativado para os fluxos, timeouts de 3 minutos e nenhum limite de tamanho no corpo das requisições, que o próprio ntfy limita. Ele escuta na porta 80 para que o Certbot possa 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 já redirecionar para HTTPS, publique em endereços https:// em seus scripts. Para milhares de inscritos, a documentação aumenta worker_connections em nginx.conf e o LimitNOFILE do serviço Nginx, para o dobro das conexões que você pretende atender.
Os aplicativos do ntfy adicionam tópicos de seu servidor do mesmo jeito que os da ntfy.sh: informe o endereço dele ao adicionar o tópico e, para um tópico protegido, o nome de usuário e a senha de um usuário que tenha acesso a ele. O aplicativo web é servido no próprio endereço do servidor.
ntfy webpush keys e de um certificado HTTPS válido.Acrescente uma linha ao server.yml e depois reinicie o contêiner:
upstream-base-url: "https://ntfy.sh"
Para cada mensagem, seu servidor publica então na ntfy.sh uma requisição de consulta, que contém apenas o ID da mensagem e o hash SHA-256 da URL do tópico. A ntfy.sh a repassa ao dispositivo pelo serviço de notificações da Apple, e o aplicativo busca a mensagem em seu servidor. O texto que passa pela ntfy.sh é sempre o mesmo, “New message”, seja qual for seu. Sem essa configuração, as notificações chegam do mesmo jeito, com um atraso que pode chegar a várias horas conforme o estado do celular. upstream-access-token acrescenta um token se você ultrapassar os limites de taxa da ntfy.sh.
O ntfy limita cada visitante, identificado pelo endereço IP dele e, em IPv6, pela sub-rede /64 dele. Esses limites protegem o servidor contra abusos; em um uso normal, diz a documentação, você não deveria atingi-los. Acima deles, o servidor responde 429 Too Many Requests. Os valores padrão:
| Configuração | Padrão | O que limita |
|---|---|---|
visitor-request-limit-burst | 60 | As requisições de um visitante em uma rajada |
visitor-request-limit-replenish | 5s | O ritmo de recarga: uma requisição a cada 5 segundos |
visitor-subscription-limit | 30 | As conexões abertas por visitante |
visitor-message-daily-limit | Nenhum | As mensagens por dia, reguladas de outra forma pelo limite de requisições |
visitor-email-limit-burst | 16 | Os e-mails em uma rajada, 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 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, ela vira anexo |
visitor-request-limit-exempt-hosts, uma lista de endereços IP ou de nomes de host.ntfy tier, dão limites mais altos a algumas contas.attachment-file-size-limit, 15M por padrão, limita cada arquivo, attachment-total-size-limit, 5G, o armazenamento total, e attachment-expiry-duration, 3h, o tempo de vida deles. Um anexo nunca dura mais que a mensagem dele: para guardar os anexos por mais tempo, aumente também cache-duration.O ntfy pode encaminhar uma mensagem por e-mail quando a requisição de publicação traz o cabeçalho Email, ou X-Email, com um endereço. Para isso, ele 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 relay SMTP autenticado nessa mesma porta 587: configure aqui o endereço de uma conta de e-mail que você já tenha, ou o de 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 assim que smtp-sender-addr é definido: sem eles, o servidor se recusa a iniciar.smtp-sender-verify: true restringe o envio aos endereços que cada usuário verificou na própria conta e o fecha para os usuários anônimos.server.yml: deixe esse arquivo legível só pelo dono dele, com chmod 600.Com o SQLite, o ntfy guarda cada tipo de dado em um arquivo próprio. Na instalação deste guia, tudo fica nas pastas etc e lib, ao lado do compose.yaml:
| Item | O que guarda | Fazer backup |
|---|---|---|
etc/server.yml | A configuração, incluindo os segredos SMTP e as chaves Web Push | Sim |
lib/user.db | Os usuários, as entradas de controle de acesso, os tokens e as contagens diárias | Sim |
lib/cache.db | As mensagens das últimas 12 horas, por padrão | Útil, a vida dele é curta |
lib/attachments/ | Os anexos das últimas 3 horas, por padrão | Útil, a vida dele é curta |
Arquivo web-push-file | As inscrições Web Push dos navegadores, se você o ativou | Sim |
Para uma cópia coerente dos arquivos SQLite, pare o serviço enquanto o arquivo compactado é criado:
docker compose stop
tar -czf ntfy-$(date +%F).tar.gz compose.yaml etc lib
docker compose start
Agende essa cópia em um horário tranquilo e envie-a para fora do servidor. Guardados no disco dele, esses arquivos também entram nos backups noturnos dele. Para restaurar, coloque as pastas de volta no lugar e execute docker compose up -d.
Se você perder o user.db sem nenhuma cópia, os usuários e os tokens declarados em server.yml por auth-users e auth-tokens são recriados na inicialização; os criados pela linha de comando precisam ser criados de novo.
Com o Docker, troque a tag 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 ficam no lugar, e o ntfy migra os bancos de dados sozinho na inicialização. 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 completo na inicialização, ou as contagens diárias zeradas. Leia-as antes de atualizar e copie as duas pastas logo antes. A versão 2.38.1 é uma versão de segurança, fortemente recomendada pelo projeto: ela reforça os templates de mensagens contra ataques de negação de serviço e impede que uploads lentos de anexos para o S3 e endpoints de web push que não respondem prendam memória e conexões. Ela vem depois da 2.38.0, que compartilha os limites de taxa entre os nós de um cluster e é compilada com o Go 1.27.4.
A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o ntfy continua sendo seu software, com as configurações e os dados dele.
| Assunto | Nossas equipes | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, com intervenções no servidor incluídas | O momento que convém a sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligação | A leitura dos logs de sua instância |
| ntfy | Acompanhamento proativo: erros, lentidões, conexões abertas e espaço em disco identificados, correção recomendada | A instalação, as atualizações e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA |
| Os acessos | O servidor que o sustenta, monitorado e com backup | Os usuários, as permissões dos tópicos e os tokens de seus scripts |
| Os backups | Toda noite, criptografados e guardados fora da máquina; restauração incluída | As cópias próprias do ntfy e o pedido de restauração, quando você precisar |
| A migração | Seu servidor atual migrado, grátis | O momento da virada |
Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.
Com um VPS gerenciado Simafri, nossas equipes mantêm atualizado o servidor de sua instância ntfy, monitoram-no dia e noite e intervêm sem esperar sua ligação; elas também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica por conta própria ou com seu assistente de IA. Os backups são criptografados todas as noites e guardados fora da máquina, a restauração está incluída, e a migração de seu servidor atual é grátis.
Sim. O ntfy tem licença dupla, Apache 2.0 e GPLv2: você pode rodá-lo em uma empresa sem licença a comprar. As condições delas se aplicam à redistribuição do software. Resta o custo do servidor em que ele roda.
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 os bancos de dados, e a porta 80 do contêiner publicada em 127.0.0.1:2586. Execute docker compose up -d e depois coloque um proxy reverso em HTTPS na frente dessa porta.
No server.yml, defina auth-file e auth-default-access: deny-all. Depois crie um administrador com ntfy user add --role=admin, usuários limitados com ntfy user add, e as permissões deles nos tópicos com ntfy access.
Crie um token com ntfy token add para um usuário dedicado ao script, limitado aos tópicos dele, e publique com o curl e o cabeçalho Authorization: Bearer seguido do token, em HTTPS. Um token dá acesso à conta inteira do usuário dele.
Atrás de um proxy reverso, todas as requisições 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 compartilham os mesmos limites de taxa.
Sim, com upstream-base-url: "https://ntfy.sh" no server.yml. Seu servidor faz então a ntfy.sh retransmitir um sinal que contém apenas o ID da mensagem, e o aplicativo busca a mensagem em seu servidor. Sem essa configuração, a entrega pode levar várias horas.
Faça backup de server.yml e user.db, que guardam a configuração, os usuários, as permissões e os tokens, além do arquivo Web Push se ele estiver ativado. O cache de mensagens e os anexos têm vida curta. Pare o serviço durante a cópia, para ter arquivos SQLite coerentes.
Um VPS gerenciado cobre o servidor: sistema, segurança, supervisão e backups. Nossas equipes também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica. Uma intervenção na aplicação é cobrada por hora ou por valor fechado.
Simafri
Vamos falar de seu site
Conte para a gente sobre seu projeto em poucas palavras: responderemos rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o e-mail? Escreva para a gente em support@simafri.com.