Hospedar ntfy em um VPS gerenciado: notificações push de seu próprio servidor

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.

Simon Vasconcelos Lee Por Publicado em 21 de novembro de 2026Leitura: 15 minutos

Todos os guias

O essencial

  1. O ntfy recebe uma mensagem por uma requisição HTTP PUT ou POST para um tópico e a envia na hora para os celulares, navegadores e scripts inscritos nesse tópico.
  2. A licença dupla dele, Apache 2.0 e GPLv2, permite rodá-lo livremente em uma empresa; as condições delas se aplicam à redistribuição do software.
  3. Instale-o com Docker Compose: a imagem 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.
  4. Por padrão, qualquer pessoa pode ler e escrever em todos os tópicos: defina 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.
  5. Faça backup de 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 que o ntfy faz

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.

Terminal, uma primeira mensagem
curl -d "Backup finished" https://ntfy.example.com/backups

As licenças Apache 2.0 e GPLv2, e a marca

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.

Os recursos a prever

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:

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 instalação com Docker Compose

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:

compose.yaml
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:

etc/server.yml
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
Terminal, na pasta do compose.yaml
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:

Sem Docker: o repositório Debian e Ubuntu

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:

Terminal
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".

Usuários, controle de acesso e tokens

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.

Terminal, o primeiro administrador
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.

Um usuário e um token por script

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:

Terminal
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

O script publica então com o token dele, em HTTPS:

Terminal, na máquina que publica
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.

HTTPS: o proxy reverso

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:

Com o Caddy

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:

Caddyfile
ntfy.example.com {
    reverse_proxy 127.0.0.1:2586
}

Com o Nginx

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:

/etc/nginx/sites-available/ntfy
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;
    }
}
Terminal
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 Android, iOS e web

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.

As notificações instantâneas no iOS

Acrescente uma linha ao server.yml e depois reinicie o contêiner:

etc/server.yml
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.

Os limites de taxa e os anexos

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çãoPadrãoO que limita
visitor-request-limit-burst60As requisições de um visitante em uma rajada
visitor-request-limit-replenish5sO ritmo de recarga: uma requisição a cada 5 segundos
visitor-subscription-limit30As conexões abertas por visitante
visitor-message-daily-limitNenhumAs mensagens por dia, reguladas de outra forma pelo limite de requisições
visitor-email-limit-burst16Os e-mails em uma rajada, depois um por hora
visitor-attachment-total-size-limit100MO armazenamento de anexos por visitante
visitor-attachment-daily-bandwidth-limit500MO tráfego de anexos por visitante por dia
global-topic-limit15.000O número total de tópicos do servidor
message-size-limit4KO tamanho de uma mensagem; acima dele, ela vira anexo

As notificações por e-mail

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.

etc/server.yml
smtp-sender-addr: "smtp.example.com:587"
smtp-sender-user: "ntfy@example.com"
smtp-sender-pass: "smtp-password"
smtp-sender-from: "ntfy@example.com"
Terminal
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

Os backups

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:

ItemO que guardaFazer backup
etc/server.ymlA configuração, incluindo os segredos SMTP e as chaves Web PushSim
lib/user.dbOs usuários, as entradas de controle de acesso, os tokens e as contagens diáriasSim
lib/cache.dbAs 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-fileAs inscrições Web Push dos navegadores, se você o ativouSim

Para uma cópia coerente dos arquivos SQLite, pare o serviço enquanto o arquivo compactado é criado:

Terminal, na pasta do compose.yaml
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.

As atualizações

Com o Docker, troque a tag da imagem em compose.yaml, por exemplo de v2.38.1 para a versão seguinte, e depois:

Terminal, na pasta do compose.yaml
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.

Quem faz o quê em um VPS gerenciado

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.

AssuntoNossas equipesVocê
O servidorAtualizações do sistema e de segurança, com intervenções no servidor incluídasO momento que convém a sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligaçãoA leitura dos logs de sua instância
ntfyAcompanhamento proativo: erros, lentidões, conexões abertas e espaço em disco identificados, correção recomendadaA instalação, as atualizações e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA
Os acessosO servidor que o sustenta, monitorado e com backupOs usuários, as permissões dos tópicos e os tokens de seus scripts
Os backupsToda noite, criptografados e guardados fora da máquina; restauração incluídaAs cópias próprias do ntfy e o pedido de restauração, quando você precisar
A migraçãoSeu servidor atual migrado, grátisO 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.

ntfy, em um servidor cuidado por nós

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.

Conhecer os VPS gerenciados

Perguntas frequentes

O ntfy é gratuito para uma empresa?

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.

Como instalar o ntfy com Docker Compose?

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.

Como tornar um servidor ntfy privado?

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.

Como publicar no ntfy a partir de um script com um token?

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.

Por que definir behind-proxy no ntfy?

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.

As notificações do ntfy chegam na hora a um iPhone?

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.

Como fazer backup do ntfy?

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 ntfy?

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.

Entre em contato