> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação self-hosted

> Como hospedar o Notifuse no seu próprio servidor

> [!TIP]
>
> **Prefere uma solução gerenciada?** O [Notifuse Cloud](https://cloud.notifuse.com) 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](https://www.notifuse.com/docs/assets/screenshots/setup.png)

### 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.

### 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`).

> [!WARNING]
>
> 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](#upgrading-a-docker-compose-installation)). 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](#replacing-the-secret-key) informa esse valor e a mudança a fazer.

```bash
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](#environment-variables) 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.

> [!WARNING]
>
> 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](https://github.com/Notifuse/notifuse/blob/main/CHANGELOG.md) entre a sua versão e a nova e [faça um backup](https://www.notifuse.com/pt/docs/self-hosting/backups.md). 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](https://www.notifuse.com/pt/docs/self-hosting/upgrading-postgresql.md) 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:

```bash
# 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](#environment-variables).

### 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](https://www.notifuse.com/pt/docs/features/templates.md#view-in-browser) 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.

> [!WARNING]
>
> **Caracteres especiais em arquivos .env**
>
> Em um arquivo `.env`, um valor que contém o caractere `#` (comum em senhas) **precisa** ficar entre aspas:
>
> ```bash
> # ✅ 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:**

```bash
openssl rand -base64 32
```

O Notifuse se recusa a iniciar com uma `SECRET_KEY` que tenha menos de 32 bytes.

> [!WARNING]
>
> 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](#replacing-the-secret-key).

### 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.

> [!WARNING]
>
> 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:
>
> ```bash
> # 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](https://www.notifuse.com/pt/docs/self-hosting/changing-domain.md).                                                                                      |
| `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`.                                                                                                              |

> [!NOTE]
>
> **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](https://www.notifuse.com/pt/docs/features/broadcast-campaigns.md) 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](https://www.notifuse.com/pt/docs/features/broadcast-campaigns.md#sending-speed).                                                                                                                                                                                                                                                                                                                 | `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](https://www.notifuse.com/pt/docs/features/webhooks.md) e [nós de webhook das automações](https://www.notifuse.com/pt/docs/features/automations.md#webhook-node)) 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](https://www.notifuse.com/pt/docs/self-hosting/licence.md) 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](https://www.notifuse.com/pt/docs/self-hosting/sso.md)) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                         |
| `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](https://www.notifuse.com/pt/docs/features/transactional-api.md#smtp-bridge) 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.

> [!WARNING]
>
> 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

```bash
# 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.

```bash
# 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:

```bash
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:

```bash
# 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`:

```bash
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>"
```

> [!NOTE]
>
> 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:

```bash
# 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.

```bash
#!/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.

> [!WARNING]
>
> 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](https://cloud.notifuse.com).

- [PikaPods](https://www.pikapods.com/pods?run=notifuse)
- [RepoCloud](https://repocloud.io/details/Notifuse/?ref=67eysha)
- [Sealos](https://sealos.io/products/app-store/notifuse)
- [Northflank](https://northflank.com/stacks/deploy-notifuse)
