Dica
Prefere uma solução gerenciada? O Notifuse Cloud cuida da hospedagem, da segurança, dos backups, das atualizações e da manutenção, a partir de US$ 16/mês.
Primeiros passos
O Notifuse inclui um assistente de configuração interativo. Muitas variáveis de ambiente são opcionais e podem ser definidas na interface web na primeira inicialização.
Início rápido com o assistente de configuração
- Implante o Notifuse com uma das opções abaixo
- Abra a sua instância em um navegador
- Conclua o assistente de configuração:
- Informe o email do administrador root (um ou mais)
- Confira o endpoint da API, já preenchido com o endereço da página
- Configure o servidor SMTP que envia os códigos de login e os convites, e teste a conexão
- Mantenha ou desative a verificação de atualizações e a telemetria anônima (as duas vêm ativadas por padrão)
- Se quiser, configure o login único (OpenID Connect) e a ponte SMTP
- Comece a usar o Notifuse.
Uma configuração já definida por uma variável de ambiente aparece bloqueada no assistente, com o nome da variável, e o assistente não a pede.
Opção 1: Docker Compose (recomendado)
O compose.yaml executa o Notifuse com o seu próprio PostgreSQL 18. O arquivo funciona sozinho: o servidor não precisa de um clone do repositório, só do Docker Engine 25.0 e do Compose v2.24 ou mais recente (docker compose version).
Atenção
Estes passos criam uma instalação nova. Para atualizar uma instalação em execução, mantenha o .env dela e a SECRET_KEY que ele contém, porque uma chave nova sozinha deixa os seus dados armazenados ilegíveis (veja Atualizar). Uma instalação iniciada com o compose.yaml antes da versão 42.0 sem definir SECRET_KEY roda com um valor padrão que o Notifuse agora recusa: Substituir a chave secreta informa esse valor e a mudança a fazer.
mkdir notifuse && cd notifuse
curl -fsSL https://raw.githubusercontent.com/Notifuse/notifuse/main/compose.yaml -o compose.yaml
# Generate the secret key and the database password once, and keep them:
# the key encrypts your stored data. An existing .env is left alone.
test -e .env || cat > .env <<EOF
SECRET_KEY=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -hex 24)
EOF
docker compose up -d
Isso inicia o Notifuse na porta 8081, com o PostgreSQL acessível apenas a partir do próprio servidor (127.0.0.1:5433). Na primeira inicialização, o assistente de configuração ajuda você a configurar a instância. Você também pode definir variáveis de ambiente no arquivo .env: todas as variáveis dele chegam ao Notifuse.
O Notifuse serve HTTP simples. Coloque um proxy reverso com TLS na frente dele antes de apontar um domínio, e defina HTTP_BIND=127.0.0.1 no .env quando esse proxy rodar no mesmo servidor.
Atenção
O Compose dá ao volume do banco de dados o nome da pasta que contém o compose.yaml (aqui, notifuse_postgres-data). Não mude o nome dessa pasta: em uma pasta renomeada ou movida, docker compose up -d inicia uma instalação nova com um banco de dados vazio. docker compose down -v apaga o banco de dados.
Atualizar uma instalação Docker Compose
Leia as entradas do changelog entre a sua versão e a nova e faça um backup. Depois baixe o compose.yaml da nova versão por cima do seu (ou defina NOTIFUSE_VERSION=v44.0 no .env para escolher a versão) e execute docker compose up -d.
A versão 44.0 migra o compose.yaml para o PostgreSQL 18: o primeiro docker compose up -d copia os seus dados do PostgreSQL 17 para um segundo volume e depois os atualiza. Atualizar o PostgreSQL explica o que acontece, como verificar e como voltar atrás.
A partir de um clone do repositório
Em um clone, o mesmo arquivo compila o Notifuse a partir do código-fonte: docker compose up -d --build, ou docker compose watch para recompilar a cada alteração. Sem --build, ele executa a imagem publicada para a versão que o arquivo indica. Uma versão ainda não publicada, na branch dev, é compilada a partir do checkout. Até a versão 43, o compose.yaml sempre compilava a partir do checkout.
Opção 2: Docker standalone (produção)
Para implantações em produção, use a imagem Docker standalone com o seu próprio banco de dados PostgreSQL:
# Generate SECRET_KEY once with: openssl rand -base64 32, and keep it: it encrypts your stored data
docker run -d --name notifuse -p 8080:8080 \
-e SECRET_KEY=<your secret key> \
notifuse/notifuse:latest
Na primeira inicialização, o assistente de configuração ajuda você a configurar a instância. Você também pode definir variáveis de ambiente.
Banco de dados PostgreSQL (somente opção 2)
Com a opção Docker standalone, você pode usar qualquer banco de dados PostgreSQL com credenciais root. O Notifuse cria o seu próprio banco de dados do sistema.
Versão: PostgreSQL 17 ou superior (o Notifuse se recusa a iniciar em um servidor mais antigo); o compose.yaml vem com o PostgreSQL 18
O Notifuse cria um banco de dados para cada workspace, para evitar problemas de multi-tenancy, e por isso precisa de credenciais root.
Observação: o Docker Compose já inclui o PostgreSQL, então isso não se aplica a ele.
Um servidor SMTP
O Notifuse precisa de um servidor SMTP para enviar os emails do sistema, como os códigos de login e os emails de convite.
Com o SES, você pode criar credenciais SMTP na seção de configurações SMTP do painel do SES.
Um endpoint público da API
O Notifuse precisa de um endpoint público da API acessível pela web, por exemplo https://emails.yourcompany.com.
Atrás de um proxy reverso, repasse ao Notifuse o cabeçalho Host original, ou defina X-Forwarded-Host com ele. As versões web dos emails só abrem no domínio com que o link foi enviado e no API_ENDPOINT. Um proxy que substitui Host pelo endereço do upstream, sem definir X-Forwarded-Host, torna todas as versões web indisponíveis. Um proxy que o substitui pelo host do API_ENDPOINT deixa qualquer domínio personalizado exibir as versões web de todos os workspaces.
Variáveis de ambiente
Com o assistente de configuração, muitas variáveis de ambiente são opcionais e podem ser definidas na interface web. Uma variável de ambiente definida sempre tem prioridade sobre a configuração salva no banco de dados.
Atenção
Caracteres especiais em arquivos .env
Em um arquivo .env, um valor que contém o caractere # (comum em senhas) precisa ficar entre aspas:
# ✅ CORRECT - value is quoted
DB_PASSWORD="mypass#word123"
SMTP_PASSWORD="smtp#pass456"
# ❌ INCORRECT - will be truncated at the # character
DB_PASSWORD=mypass#word123 # parsed as "mypass"
SMTP_PASSWORD=smtp#pass456 # parsed as "smtp"Isso vale só para arquivos .env, não para variáveis definidas diretamente no shell, no Docker Compose ou em uma plataforma de orquestração de contêineres.
Variáveis obrigatórias
| Variável | Descrição |
|---|---|
DB_HOST | Host do PostgreSQL (por exemplo, localhost ou db.yourcompany.com) |
DB_PORT | Porta do PostgreSQL (por exemplo, 5432) |
DB_USER | Usuário do banco de dados (por exemplo, postgres) |
DB_PASSWORD | Senha do banco de dados (por exemplo, postgres) |
SECRET_KEY | Chave secreta de criptografia e assinatura (gere com o comando abaixo) |
Gerar a SECRET_KEY:
openssl rand -base64 32
O Notifuse se recusa a iniciar com uma SECRET_KEY que tenha menos de 32 bytes.
Atenção
Nunca substitua a sua SECRET_KEY apenas por um novo valor. Ela criptografa todos os segredos das
integrações dos workspaces (chaves API dos provedores de email, senhas SMTP etc.), que uma chave nova
sozinha não consegue ler. Para trocá-la, siga Substituir a chave secreta.
Substituir a chave secreta
A SECRET_KEY pode listar várias chaves separadas por vírgulas (uma vírgula que faz parte de uma chave
é escrita duas vezes). A primeira chave criptografa e assina; as outras só permitem que o Notifuse leia
os dados armazenados com elas. Quando o Notifuse inicia com uma lista, ele recriptografa esses dados com
a primeira chave, em uma única transação, antes de atender qualquer requisição. Para substituir a sua chave:
- Gere uma nova chave com
openssl rand -base64 32. - Coloque-a primeiro e a sua chave atual depois dela:
SECRET_KEY=<new key>,<current key>. Se a sua chave atual contém uma vírgula, escreva essa vírgula duas vezes. Se ela começa ou termina com uma vírgula, coloque um espaço entre ela e a vírgula que separa as chaves (SECRET_KEY=<new key>, ,,<rest of the key>). Uma versão anterior à 42.0 lê a lista inteira como uma única chave: ao atualizar para a 42.0, defina a lista na mesma etapa. - Pare todas as instâncias do Notifuse e depois inicie todas com esse valor. Uma instância que ainda roda só com a chave atual não consegue ler os dados que as outras recriptografaram, e uma instância que roda com a lista não consegue ler o que essa instância grava até a próxima inicialização com a lista.
- Quando todas as instâncias estiverem rodando com esse valor, defina a
SECRET_KEYsó com a nova chave, sem aspas nem espaços em volta: uma chave única é usada exatamente como está escrita. Se ela não abrir nenhum dos workspaces armazenados (ou, enquanto nenhum estiver armazenado, nenhuma das configurações do sistema criptografadas), o Notifuse não inicia.
Se a chave de um workspace, ou uma credencial que ele usa, não abre com nenhuma das chaves listadas, o Notifuse não inicia, não altera nada e indica o nome desse workspace. Uma configuração do sistema criptografada que nenhuma delas abre (uma credencial SMTP ou o client secret OIDC salvos no assistente de configuração, o certificado ou a chave TLS da ponte SMTP) fica como está e aparece em um aviso nos logs de inicialização, e o Notifuse roda sem ela. Para mantê-la, liste a chave com que ela foi criptografada. O Notifuse não inicia, e indica a configuração, quando o login único ou a ponte SMTP estiverem ativados e precisarem dela, ou quando ainda não há nenhum workspace armazenado e nenhuma dessas configurações abre.
Substituir a chave desconecta todo mundo. As chaves API precisam ser excluídas e criadas de novo, os
convites pendentes precisam ser reenviados, e os scripts que chamam user.rootSignin passam a assinar
com a nova chave. Um cliente da API que salva uma integração com as credenciais criptografadas que leu
antes da troca é recusado até ler o workspace de novo. Os backups do banco de dados feitos antes da
troca continuam precisando da chave antiga. Os dados guardados no banco de dados de cada workspace,
como o histórico de mensagens, são criptografados com a chave própria desse workspace e não são afetados.
Atenção
Antes da versão 42.0, o compose.yaml fornecia uma SECRET_KEY padrão e o env.example, um
placeholder. O Notifuse se recusa a iniciar quando a primeira chave da SECRET_KEY é um desses valores
ou tem menos de 32 bytes, e lê uma vírgula simples como separador entre chaves: se a sua chave contém
uma vírgula, escreva cada uma das vírgulas dela duas vezes ao atualizar. Se a sua instalação roda com
um desses valores, substitua-o como descrito acima, mantendo-o depois da nova chave, na mesma etapa da
atualização para a 42.0. Se você começou com o compose.yaml sem definir SECRET_KEY, a sua chave
atual é o antigo valor padrão:
# Put the output of openssl rand -base64 32 before the comma
SECRET_KEY=<new key>,d04zCk3Fa45oOjDWHpAvc1AZxnLdGffOnNWK+Jt2yXf37+FTfuMMHb8flcfPMqLluRR3rvhbr555r6j1DEigrA==Variáveis da aplicação (opcionais com o assistente de configuração)
Defina-as no assistente de configuração na primeira inicialização, ou como variáveis de ambiente, que sempre têm prioridade sobre o assistente.
| Variável | Descrição |
|---|---|
ROOT_EMAIL | Email do administrador root (por exemplo, admin@yourcompany.com). Aceita vários emails separados por vírgula ou ponto e vírgula para dar acesso root a vários administradores (por exemplo, alice@yourcompany.com,bob@yourcompany.com); a comparação diferencia maiúsculas de minúsculas. |
API_ENDPOINT | URL pública do endpoint da API (por exemplo, https://emails.yourcompany.com). Para mudar de domínio depois, veja Mudar de domínio. |
SMTP_HOST | Host do servidor SMTP (por exemplo, smtp.gmail.com) |
SMTP_PORT | Porta do servidor SMTP (por exemplo, 587 ou 465) |
SMTP_USERNAME | Usuário SMTP (por exemplo, noreply@yourcompany.com) |
SMTP_PASSWORD | Senha SMTP (por exemplo, your_smtp_password) |
SMTP_FROM_EMAIL | Endereço de email do remetente (por exemplo, noreply@yourcompany.com) |
SMTP_FROM_NAME | Nome do remetente (por exemplo, Your Company Name) |
SMTP_EHLO_HOSTNAME | Hostname EHLO personalizado para as conexões SMTP (por exemplo, mail.yourdomain.com). Quando vazio, usa o host SMTP. Útil quando os servidores SMTP rejeitam EHLO localhost. |
Nota
Vários usuários root: o ROOT_EMAIL pode conter mais de um email
(separados por vírgula ou ponto e vírgula), para que uma instância
compartilhada tenha vários administradores com privilégios root: criar
workspaces, acessar as configurações do sistema e se autenticar
programaticamente. O Notifuse cria uma conta de usuário para cada email listado
na inicialização, então cada root pode entrar na hora. A comparação
diferencia maiúsculas de minúsculas, e um único email funciona exatamente
como antes. O assistente de configuração define o primeiro root (o
principal); adicione outros lá, em forma de lista, ou com a variável de
ambiente ROOT_EMAIL.
Variáveis opcionais
| Variável | Descrição | Padrão |
|---|---|---|
| Configuração do servidor | ||
SERVER_PORT | Porta em que o servidor escuta (por exemplo, 8080) | 8080 |
SERVER_HOST | Endereço de host em que o servidor escuta (por exemplo, 0.0.0.0) | 0.0.0.0 |
CORS_ALLOW_ORIGIN | Origens autorizadas a chamar a API a partir de um navegador: *, uma origem ou uma lista separada por vírgulas (por exemplo, https://yourapp.com,https://admin.yourapp.com; listas exigem a 41.1 ou posterior). Um valor restrito precisa incluir todos os domínios personalizados dos workspaces, cujo console e cuja central de notificações chamam a API a partir da própria origem. | * |
ENVIRONMENT | Modo de ambiente (por exemplo, production) | production |
LOG_LEVEL | Nível de log (por exemplo, debug ou warn) | info |
| Configuração do banco de dados | ||
DB_PREFIX | Prefixo dos nomes dos bancos de dados do sistema e dos workspaces (por exemplo, notifuse para notifuse_system e notifuse_ws_*) | notifuse |
DB_NAME | Nome do banco de dados (por exemplo, notifuse_system) | ${DB_PREFIX}_system |
DB_SSLMODE | Modo SSL do banco de dados (por exemplo, require ou disable) | require |
DB_EXPECT_EXISTING | true impede que o Notifuse crie ou inicialize o banco de dados do sistema ou crie um banco de workspace ausente. Defina-a em um servidor que já deve conter os dados (uma atualização, uma restauração), para que um PostgreSQL vazio pare o Notifuse em vez de iniciar uma instalação nova | false |
DB_MAX_CONNECTIONS | Total máximo de conexões somando todos os bancos de dados (por exemplo, 100) | 100 |
DB_MAX_CONNECTIONS_PER_DB | Máximo de conexões por banco de dados de workspace (por exemplo, 3) | 3 |
DB_CONNECTION_MAX_LIFETIME | Tempo máximo de vida de uma conexão (por exemplo, 10m) | 10m |
DB_CONNECTION_MAX_IDLE_TIME | Tempo máximo ocioso antes de fechar a conexão (por exemplo, 5m) | 5m |
| Configuração do agendador de tarefas | ||
TASK_SCHEDULER_ENABLED | Ativa o agendador de tarefas interno (por exemplo, true ou false) | true |
TASK_SCHEDULER_INTERVAL | Intervalo de execução das tarefas, em segundos (por exemplo, 30) | 30 |
TASK_SCHEDULER_MAX_TASKS | Máximo de tarefas simultâneas (por exemplo, 10) | 10 |
| Configuração de broadcasts | ||
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS | Permite que os feeds de dados dos broadcasts busquem dados em endereços privados, de loopback e link-local. Isso desativa a proteção contra SSRF nas requisições de feed de dados: ative só em implantações confiáveis que buscam feeds na sua rede interna de propósito (por exemplo, true). | false |
EMAIL_QUEUE_CONCURRENCY | Quantos emails cada integração de email que não seja SMTP envia ao mesmo tempo para broadcasts e automações, por instância do Notifuse, entre 1 e 50 (por exemplo, 20; 42.0 ou posterior). Veja Velocidade de envio. | 10 |
EMAIL_QUEUE_SMTP_CONCURRENCY | O mesmo para as integrações SMTP, entre 1 e 50 (42.0 ou posterior). Aumente só se o seu servidor SMTP aceitar várias conexões ao mesmo tempo (por exemplo, 4). | 1 |
| Configuração de webhooks | ||
WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS | Permite que os webhooks de saída (assinaturas de webhook e nós de webhook das automações) alcancem endereços privados, de loopback e link-local. Isso desativa a proteção contra SSRF para eles: ative só em implantações confiáveis que entregam webhooks na sua rede interna de propósito, como um n8n na mesma rede Docker (por exemplo, true). Enquanto essa variável estiver desativada, os webhooks de saída se conectam diretamente e ignoram HTTP_PROXY/HTTPS_PROXY. | false |
| Licença | ||
NOTIFUSE_LICENSE_KEY | Uma chave de licença self-hosted. Tem prioridade sobre uma chave colada no console. Não é necessária para rodar o Notifuse. | - |
| Configurações de privacidade | ||
TELEMETRY | Envia estatísticas de uso anônimas (por exemplo, true ou false) | true |
CHECK_FOR_UPDATES | Verifica se há novas versões (por exemplo, true ou false) | true |
| Configuração da ponte SMTP | ||
SMTP_BRIDGE_ENABLED | Ativa o servidor da ponte SMTP para emails transacionais (por exemplo, true ou false) | false |
SMTP_BRIDGE_PORT | Porta da ponte SMTP (por exemplo, 587 para STARTTLS, 465 para TLS implícito) | 587 |
SMTP_BRIDGE_DOMAIN | Nome de domínio público da ponte SMTP (por exemplo, smtp.yourdomain.com) | localhost |
SMTP_BRIDGE_TLS | Modo TLS: starttls, implicit ou off (veja abaixo). Definido automaticamente quando não configurado. | auto |
SMTP_BRIDGE_TLS_CERT_BASE64 | Certificado TLS codificado em Base64 (obrigatório para starttls e implicit) | - |
SMTP_BRIDGE_TLS_KEY_BASE64 | Chave privada TLS codificada em Base64 (obrigatória para starttls e implicit) | - |
| Login único (OIDC) (veja o guia de SSO) | ||
OIDC_ENABLED | Ativa o login único via OpenID Connect (por exemplo, true ou false) | false |
OIDC_ISSUER_URL | URL do issuer do IdP, precisa ser https (por exemplo, https://accounts.google.com) | - |
OIDC_CLIENT_ID | Client ID OAuth2 do seu provedor de identidade | - |
OIDC_CLIENT_SECRET | Client secret OAuth2 (criptografado em repouso; nunca enviado ao navegador) | - |
OIDC_REDIRECT_URI | URL de callback registrada no IdP. Derivada do API_ENDPOINT quando vazia. | <API_ENDPOINT>/api/user.oidc.callback |
OIDC_SCOPES | Escopos separados por espaço (openid sempre incluído) | openid email profile |
OIDC_BUTTON_LABEL | Texto do botão de login | Sign in with SSO |
OIDC_AUTO_CREATE_USERS | Cria contas automaticamente no primeiro login por SSO (exige OIDC_ALLOWED_DOMAINS) | false |
OIDC_ALLOWED_DOMAINS | Lista de domínios de email permitidos, separados por vírgula ou ponto e vírgula, que controla a criação automática | - |
| Configuração de tracing | ||
TRACING_ENABLED | Ativa o tracing (por exemplo, true) | false |
TRACING_SERVICE_NAME | Nome do serviço para o tracing (por exemplo, notifuse-production) | notifuse-api |
TRACING_SAMPLING_PROBABILITY | Probabilidade de amostragem (por exemplo, 0.05) | 0.1 |
TRACING_TRACE_EXPORTER | Exportador de traces: jaeger/zipkin/stackdriver/datadog/xray/none (por exemplo, jaeger ou datadog) | none |
TRACING_JAEGER_ENDPOINT | Endpoint do Jaeger (por exemplo, http://jaeger:14268/api/traces) | http://localhost:14268/api/traces |
TRACING_ZIPKIN_ENDPOINT | Endpoint do Zipkin (por exemplo, http://zipkin:9411/api/v2/spans) | http://localhost:9411/api/v2/spans |
TRACING_STACKDRIVER_PROJECT_ID | ID do projeto Stackdriver (por exemplo, my-gcp-project-id) | - |
TRACING_AZURE_INSTRUMENTATION_KEY | Chave de instrumentação do Azure Monitor (por exemplo, 12345678-1234-1234-1234-123456789012) | - |
TRACING_DATADOG_AGENT_ADDRESS | Endereço do agente Datadog (por exemplo, datadog-agent:8126) | localhost:8126 |
TRACING_DATADOG_API_KEY | Chave API do Datadog (por exemplo, 1234567890abcdef1234567890abcdef) | - |
TRACING_XRAY_REGION | Região do AWS X-Ray (por exemplo, us-east-1) | us-west-2 |
TRACING_AGENT_ENDPOINT | Endpoint genérico do agente (por exemplo, monitoring-agent:8126) | localhost:8126 |
TRACING_METRICS_EXPORTER | Exportador de métricas: stackdriver/prometheus/datadog/none (por exemplo, prometheus) | none |
TRACING_PROMETHEUS_PORT | Porta das métricas do Prometheus (por exemplo, 9464) | 9464 |
Configuração da ponte SMTP
A ponte SMTP conecta ao Notifuse aplicações SaaS que só oferecem integração por SMTP (como Supabase Auth, Firebase ou Auth0). Assim, os emails delas usam os designs e a identidade visual que você cria no editor MJML do Notifuse em vez dos templates padrão do SaaS.
Veja a documentação de uso da ponte SMTP para exemplos de envio de emails depois da configuração.
Modos TLS
A ponte aceita três modos TLS, definidos por SMTP_BRIDGE_TLS:
| Modo | Descrição | Porta típica |
|---|---|---|
starttls | Escuta em texto simples; os clientes precisam passar para TLS com STARTTLS antes do AUTH. Padrão quando os certificados são fornecidos. | 587 |
implicit | TLS desde o primeiro byte (SMTPS). Necessário para clientes que só falam TLS implícito. | 465 |
off | Sem TLS. Só é seguro atrás de um proxy reverso com terminação TLS (HAProxy, Caddy layer4, stunnel, nginx Mail, Postfix) em uma rede confiável. | qualquer |
Quando SMTP_BRIDGE_TLS não está definido, o Notifuse escolhe starttls se o certificado e a chave forem fornecidos; caso contrário, off em desenvolvimento.
Atenção
Em produção (ENVIRONMENT=production), a ponte se recusa a iniciar sem TLS configurado. Forneça SMTP_BRIDGE_TLS_CERT_BASE64 e SMTP_BRIDGE_TLS_KEY_BASE64, ou defina SMTP_BRIDGE_TLS=off explicitamente se você roda atrás de um proxy reverso com terminação TLS.
Configuração de produção com Let’s Encrypt
Em produção, use certificados TLS válidos do Let’s Encrypt, obtidos com o certbot e um desafio DNS.
Passo 1: instalar o Certbot
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install certbot
# macOS
brew install certbot
# CentOS/RHEL
sudo yum install certbot
Passo 2: gerar o certificado com um desafio DNS
O desafio DNS é o recomendado: ele não precisa das portas 80 ou 443 abertas e funciona mesmo que o seu servidor SMTP use outra porta.
# Generate certificate using DNS challenge
sudo certbot certonly \
--manual \
--preferred-challenges dns \
--email admin@yourdomain.com \
--agree-tos \
-d smtp.yourdomain.com
Em seguida, o certbot pede que você crie um registro DNS TXT:
Please deploy a DNS TXT record under the name
_acme-challenge.smtp.yourdomain.com with the following value:
XyZ123AbC456...
Before continuing, verify the record is deployed by running:
dig -t txt _acme-challenge.smtp.yourdomain.com
Passo 3: adicionar o registro DNS TXT
Adicione o registro TXT no seu provedor de DNS:
Type: TXT
Name: _acme-challenge.smtp
Value: XyZ123AbC456... (the value provided by certbot)
TTL: 300 (5 minutes)
Aguarde alguns minutos pela propagação do DNS e depois verifique o registro:
dig -t txt _acme-challenge.smtp.yourdomain.com
# Or using nslookup
nslookup -type=TXT _acme-challenge.smtp.yourdomain.com
Quando o registro estiver verificado, pressione Enter no certbot para continuar.
Passo 4: codificar os certificados em Base64
Depois que o certbot gerar os certificados, codifique-os em base64:
# Certificate location (typically):
# Certificate: /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem
# Private Key: /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem
# Encode certificate to base64 (single line)
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem | base64 -w 0 > cert_base64.txt
# Encode private key to base64 (single line)
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem | base64 -w 0 > key_base64.txt
# On macOS, omit the -w flag:
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem | base64 > cert_base64.txt
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem | base64 > key_base64.txt
Passo 5: adicionar às variáveis de ambiente
Copie os valores codificados em base64 para o seu arquivo .env:
SMTP_BRIDGE_ENABLED=true
SMTP_BRIDGE_DOMAIN=smtp.yourdomain.com
SMTP_BRIDGE_PORT=587
SMTP_BRIDGE_TLS=starttls
SMTP_BRIDGE_TLS_CERT_BASE64="<paste-cert-base64-here>"
SMTP_BRIDGE_TLS_KEY_BASE64="<paste-key-base64-here>"
Nota
O certbot configura um cron job de renovação. Depois de cada renovação, codifique os certificados em base64 de novo e atualize as suas variáveis de ambiente.
Configuração de desenvolvimento com certificados autoassinados
Para desenvolvimento local, você pode usar certificados autoassinados:
# Using the provided script
./scripts/generate-dev-certs.sh localapi.notifuse.com
# Or manually with openssl
openssl req -x509 -newkey rsa:2048 \
-keyout dev-cert.key.pem \
-out dev-cert.cert.pem \
-days 365 -nodes \
-subj "/CN=localhost" \
-addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
# Encode to base64
cat dev-cert.cert.pem | base64 > cert_base64.txt
cat dev-cert.key.pem | base64 > key_base64.txt
Atenção: certificados autoassinados servem só para desenvolvimento. Nunca os use em produção.
Gerenciamento da configuração
O assistente de configuração serve para implantações rápidas e testes: ele guarda a configuração de forma segura no banco de dados, e você a gerencia na interface web. Em produção, as variáveis de ambiente são as recomendadas: protegem melhor os dados sensíveis e deixam o seu pipeline de implantação gerenciar a configuração. Quando uma configuração está definida nos dois lugares, a variável de ambiente sempre prevalece.
Em produção, recomendamos variáveis de ambiente para a configuração sensível (credenciais SMTP, SECRET_KEY) e o assistente de configuração ou a interface de administração para o resto (endpoint da API etc.).
Autenticação programática
Em pipelines de CI/CD e implantações automatizadas, um usuário root pode se autenticar programaticamente com uma assinatura HMAC-SHA256 em vez de um link mágico. Quando o ROOT_EMAIL lista vários endereços, use qualquer um deles como ROOT_EMAIL abaixo: o email assinado precisa ser exatamente igual a um dos emails root configurados.
#!/bin/bash
# Configuration
NOTIFUSE_URL="https://your-notifuse-instance.com"
SECRET_KEY="your-secret-key" # the first key when SECRET_KEY lists several
ROOT_EMAIL="admin@example.com"
TIMESTAMP=$(date +%s)
# Generate HMAC signature
MESSAGE="${ROOT_EMAIL}:${TIMESTAMP}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET_KEY" | awk '{print $2}')
# Authenticate and get JWT token
curl -X POST "${NOTIFUSE_URL}/api/user.rootSignin" \
-H "Content-Type: application/json" \
-d "{\"email\":\"${ROOT_EMAIL}\",\"timestamp\":${TIMESTAMP},\"signature\":\"${SIGNATURE}\"}"
O endpoint devolve um token JWT para as requisições seguintes à API. O timestamp precisa estar com diferença de até 60 segundos do horário do servidor, e as requisições são limitadas a 5 tentativas a cada 5 minutos.
Plataformas de hospedagem de terceiros
O Notifuse também está disponível nas seguintes plataformas de terceiros.
Atenção
Essas plataformas não têm suporte oficial e muitas vezes rodam versões desatualizadas do Notifuse. Para ter a versão mais recente, atualizações automáticas e suporte oficial, use o Notifuse Cloud.
