Pular para o conteúdo

Auto-hospedagem

Instalação self-hosted

Como hospedar o Notifuse no seu próprio servidor

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.

O assistente de configuração preenchido: administrador, envio de emails do sistema (SMTP), atualizações e telemetria, login único e ponte SMTP, com o que falta preencher ao lado

Início rápido com o assistente de configuração

  1. Implante o Notifuse com uma das opções abaixo
  2. Abra a sua instância em um navegador
  3. 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
  4. 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.

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ávelDescrição
DB_HOSTHost do PostgreSQL (por exemplo, localhost ou db.yourcompany.com)
DB_PORTPorta do PostgreSQL (por exemplo, 5432)
DB_USERUsuário do banco de dados (por exemplo, postgres)
DB_PASSWORDSenha do banco de dados (por exemplo, postgres)
SECRET_KEYChave 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:

  1. Gere uma nova chave com openssl rand -base64 32.
  2. 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.
  3. 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.
  4. Quando todas as instâncias estiverem rodando com esse valor, defina a SECRET_KEY só 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ávelDescrição
ROOT_EMAILEmail 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_ENDPOINTURL pública do endpoint da API (por exemplo, https://emails.yourcompany.com). Para mudar de domínio depois, veja Mudar de domínio.
SMTP_HOSTHost do servidor SMTP (por exemplo, smtp.gmail.com)
SMTP_PORTPorta do servidor SMTP (por exemplo, 587 ou 465)
SMTP_USERNAMEUsuário SMTP (por exemplo, noreply@yourcompany.com)
SMTP_PASSWORDSenha SMTP (por exemplo, your_smtp_password)
SMTP_FROM_EMAILEndereço de email do remetente (por exemplo, noreply@yourcompany.com)
SMTP_FROM_NAMENome do remetente (por exemplo, Your Company Name)
SMTP_EHLO_HOSTNAMEHostname 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ávelDescriçãoPadrão
Configuração do servidor
SERVER_PORTPorta em que o servidor escuta (por exemplo, 8080)8080
SERVER_HOSTEndereço de host em que o servidor escuta (por exemplo, 0.0.0.0)0.0.0.0
CORS_ALLOW_ORIGINOrigens 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.*
ENVIRONMENTModo de ambiente (por exemplo, production)production
LOG_LEVELNível de log (por exemplo, debug ou warn)info
Configuração do banco de dados
DB_PREFIXPrefixo dos nomes dos bancos de dados do sistema e dos workspaces (por exemplo, notifuse para notifuse_system e notifuse_ws_*)notifuse
DB_NAMENome do banco de dados (por exemplo, notifuse_system)${DB_PREFIX}_system
DB_SSLMODEModo SSL do banco de dados (por exemplo, require ou disable)require
DB_EXPECT_EXISTINGtrue 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 novafalse
DB_MAX_CONNECTIONSTotal máximo de conexões somando todos os bancos de dados (por exemplo, 100)100
DB_MAX_CONNECTIONS_PER_DBMáximo de conexões por banco de dados de workspace (por exemplo, 3)3
DB_CONNECTION_MAX_LIFETIMETempo máximo de vida de uma conexão (por exemplo, 10m)10m
DB_CONNECTION_MAX_IDLE_TIMETempo máximo ocioso antes de fechar a conexão (por exemplo, 5m)5m
Configuração do agendador de tarefas
TASK_SCHEDULER_ENABLEDAtiva o agendador de tarefas interno (por exemplo, true ou false)true
TASK_SCHEDULER_INTERVALIntervalo de execução das tarefas, em segundos (por exemplo, 30)30
TASK_SCHEDULER_MAX_TASKSMáximo de tarefas simultâneas (por exemplo, 10)10
Configuração de broadcasts
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTSPermite 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_CONCURRENCYQuantos 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_CONCURRENCYO 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_HOSTSPermite 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_KEYUma 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
TELEMETRYEnvia estatísticas de uso anônimas (por exemplo, true ou false)true
CHECK_FOR_UPDATESVerifica se há novas versões (por exemplo, true ou false)true
Configuração da ponte SMTP
SMTP_BRIDGE_ENABLEDAtiva o servidor da ponte SMTP para emails transacionais (por exemplo, true ou false)false
SMTP_BRIDGE_PORTPorta da ponte SMTP (por exemplo, 587 para STARTTLS, 465 para TLS implícito)587
SMTP_BRIDGE_DOMAINNome de domínio público da ponte SMTP (por exemplo, smtp.yourdomain.com)localhost
SMTP_BRIDGE_TLSModo TLS: starttls, implicit ou off (veja abaixo). Definido automaticamente quando não configurado.auto
SMTP_BRIDGE_TLS_CERT_BASE64Certificado TLS codificado em Base64 (obrigatório para starttls e implicit)-
SMTP_BRIDGE_TLS_KEY_BASE64Chave privada TLS codificada em Base64 (obrigatória para starttls e implicit)-
Login único (OIDC) (veja o guia de SSO)
OIDC_ENABLEDAtiva o login único via OpenID Connect (por exemplo, true ou false)false
OIDC_ISSUER_URLURL do issuer do IdP, precisa ser https (por exemplo, https://accounts.google.com)-
OIDC_CLIENT_IDClient ID OAuth2 do seu provedor de identidade-
OIDC_CLIENT_SECRETClient secret OAuth2 (criptografado em repouso; nunca enviado ao navegador)-
OIDC_REDIRECT_URIURL de callback registrada no IdP. Derivada do API_ENDPOINT quando vazia.<API_ENDPOINT>/api/user.oidc.callback
OIDC_SCOPESEscopos separados por espaço (openid sempre incluído)openid email profile
OIDC_BUTTON_LABELTexto do botão de loginSign in with SSO
OIDC_AUTO_CREATE_USERSCria contas automaticamente no primeiro login por SSO (exige OIDC_ALLOWED_DOMAINS)false
OIDC_ALLOWED_DOMAINSLista 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_ENABLEDAtiva o tracing (por exemplo, true)false
TRACING_SERVICE_NAMENome do serviço para o tracing (por exemplo, notifuse-production)notifuse-api
TRACING_SAMPLING_PROBABILITYProbabilidade de amostragem (por exemplo, 0.05)0.1
TRACING_TRACE_EXPORTERExportador de traces: jaeger/zipkin/stackdriver/datadog/xray/none (por exemplo, jaeger ou datadog)none
TRACING_JAEGER_ENDPOINTEndpoint do Jaeger (por exemplo, http://jaeger:14268/api/traces)http://localhost:14268/api/traces
TRACING_ZIPKIN_ENDPOINTEndpoint do Zipkin (por exemplo, http://zipkin:9411/api/v2/spans)http://localhost:9411/api/v2/spans
TRACING_STACKDRIVER_PROJECT_IDID do projeto Stackdriver (por exemplo, my-gcp-project-id)-
TRACING_AZURE_INSTRUMENTATION_KEYChave de instrumentação do Azure Monitor (por exemplo, 12345678-1234-1234-1234-123456789012)-
TRACING_DATADOG_AGENT_ADDRESSEndereço do agente Datadog (por exemplo, datadog-agent:8126)localhost:8126
TRACING_DATADOG_API_KEYChave API do Datadog (por exemplo, 1234567890abcdef1234567890abcdef)-
TRACING_XRAY_REGIONRegião do AWS X-Ray (por exemplo, us-east-1)us-west-2
TRACING_AGENT_ENDPOINTEndpoint genérico do agente (por exemplo, monitoring-agent:8126)localhost:8126
TRACING_METRICS_EXPORTERExportador de métricas: stackdriver/prometheus/datadog/none (por exemplo, prometheus)none
TRACING_PROMETHEUS_PORTPorta 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:

ModoDescriçãoPorta típica
starttlsEscuta em texto simples; os clientes precisam passar para TLS com STARTTLS antes do AUTH. Padrão quando os certificados são fornecidos.587
implicitTLS desde o primeiro byte (SMTPS). Necessário para clientes que só falam TLS implícito.465
offSem 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.