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

# Variáveis de ambiente do Lerian SISBAJUD executor

> Variáveis de ambiente do Lerian SISBAJUD executor: runtime, autenticação, licença, gestão de chaves, conexão com a Mensageria, tempos de execução, listener de webhook, Midaz e streaming de eventos.

Esta página lista as variáveis de ambiente do **executor**. [Variáveis de ambiente da Lerian SISBAJUD Mensageria](/pt/rails/sisbajud/sisbajud-environment-variables) lista as variáveis da Mensageria. [Fundamentos de configuração do BYOC](/pt/reference/byoc-configuration) documenta as variáveis que todo serviço Go da Lerian compartilha: servidor, armazenamento de dados, telemetria e autenticação de plugin.

Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo, **Obrigatório**) marca as variáveis que você deve definir. `—` significa que não há padrão. Uma variável marcada como **Sensível** guarda uma credencial ou material de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Não faça commit do seu valor.

`MENSAGERIA_BASE_URL` liga o executor. Os requisitos do executor abaixo valem quando ela está definida.

## Serviço e runtime

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SERVER_ADDRESS` | **Defina como `:4029`** | Endereço de escuta da API principal. A imagem expõe a porta 4029. `/health`, `/readyz` e `/version` usam esta porta. |
| `ENVIRONMENT_NAME` | — | Ambiente de execução. `local`, `development`, `staging`, `e2e` e `test` são valores de não produção. Qualquer outro valor, e nenhum valor, executa as verificações de produção. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc` ou `saas`. Com `saas`, o boot recusa uma conexão PostgreSQL ou Redis sem TLS. Fora de `local`, o listener de webhook precisa de TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant de um deployment single-tenant. Deve ser um UUID. |
| `SYSTEMPLANE_ENABLED` | `false` | Serve a API de administração do [Systemplane](/pt/reference/platform/systemplane/overview) em `/system` e os documentos de rotas contábeis em `/tenant-system`. |

<Note>
  As verificações de produção exigem `POSTGRES_PASSWORD` e recusam `POSTGRES_SSLMODE=disable`. Com `STREAMING_ENABLED=true`, elas também exigem `STREAMING_TLS_ENABLED=true`.
</Note>

## Autenticação

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` | Verifica os bearer tokens da API principal com o Access Manager. Com `false`, o executor não serve a rotação da chave de credenciais. |
| `PLUGIN_AUTH_HOST` | **Obrigatório** | Endereço do Access Manager. O executor obtém o seu token para a Mensageria neste endereço, também quando `PLUGIN_AUTH_ENABLED` é `false`. |

## Licença

[License Manager](/pt/platform/licensing/license-manager) descreve como o produto verifica a licença.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_KEY` | **Obrigatório** | A chave de licença que a Lerian emitiu para o Lerian SISBAJUD. O boot recusa um valor vazio em qualquer ambiente. |
| `ORGANIZATION_IDS` | **Obrigatório** | Escopo da licença. Defina como `global`. Qualquer outro valor recusa o boot. |

## Gestão de chaves

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `KMS_PROVIDER` | **Obrigatório quando `ENVIRONMENT_NAME` é `production`** | Gerenciador de chaves: `vault` (HashiCorp Vault Transit) ou `aws` (AWS KMS). Qualquer outro valor recusa o boot. Com qualquer outro ambiente, um valor não definido significa `vault`. |
| `AWS_REGION` | **Obrigatório com `aws`** | Região do AWS KMS. |
| `VAULT_ADDR` | **Obrigatório com `vault`** | Endereço do seu Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` ou `approle`. Qualquer outro valor recusa o boot. |
| `VAULT_TOKEN` | **Obrigatório para `token` quando `ENVIRONMENT_NAME` é `production`** | Token do Vault. Sensível. |
| `VAULT_APPROLE_ROLE_ID` | **Obrigatório para `approle`** | Role ID do AppRole. Sensível. |
| `VAULT_APPROLE_SECRET_ID` | **Obrigatório para `approle`** | Secret ID do AppRole. Sensível. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Caminho de montagem do engine Transit. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout de cada requisição ao Vault, em segundos. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renova o token do Vault em segundo plano. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Tempo mínimo entre duas renovações, em segundos. |

## Conexão com a Mensageria

O executor chama a API de execução da Mensageria. [Integrando com o Lerian SISBAJUD](/pt/rails/sisbajud/sisbajud-integration#execution-api) a descreve.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `MENSAGERIA_BASE_URL` | **Obrigatório** | URL base da API de execução da Mensageria (`SISBAJUD_EXECUTION_ADDRESS` na Mensageria). Deve ser uma URL `https` com host. |
| `MENSAGERIA_MTLS_ENABLED` | `false` | `true` apresenta um certificado de cliente. `false` usa TLS de uma via. Qualquer outro valor recusa o boot. |
| `MENSAGERIA_TLS_CA_FILE` | **Obrigatório se `MENSAGERIA_MTLS_ENABLED=true`** | Pacote de CA que verifica a Mensageria. Com TLS de uma via, é opcional, e um valor vazio usa o repositório de confiança do sistema. |
| `MENSAGERIA_TLS_CLIENT_CERT_FILE` | **Obrigatório se `MENSAGERIA_MTLS_ENABLED=true`** | Certificado de cliente do executor. |
| `MENSAGERIA_TLS_CLIENT_KEY_FILE` | **Obrigatório se `MENSAGERIA_MTLS_ENABLED=true`** | Chave privada desse certificado. Sensível. |
| `EXECUTOR_M2M_SUBJECT` | **Obrigatório** | O `sub` do token M2M do executor. O executor o registra como dono de cada instituição que cria. |
| `MENSAGERIA_CLIENT_ID` | **Obrigatório** | Client ID do cliente M2M do executor. |
| `MENSAGERIA_CLIENT_SECRET` | **Obrigatório** | Client secret desse cliente. Sensível. O boot recusa um par com apenas um dos dois valores. |
| `STREAMING_HUB_TENANT_ID` | **Obrigatório** | Tenant das sondas canário. O executor responde a uma sonda somente quando o tenant da entrega é este valor. |

## Tempos de execução

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `EXECUTOR_TICK_EVERY` | `30s` | Intervalo do ciclo de execução. Duração Go maior que 0. |
| `EXECUTOR_HEARTBEAT_EVERY` | **Obrigatório** | Intervalo dos heartbeats de uma escrita cujo resultado não é conhecido. Duração Go maior que 0. |
| `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` | `3` | Número de heartbeats sem mudança antes de a ordem ir para uma decisão humana. |
| `RESPONSE_DEADLINE_MARGIN` | **Obrigatório** | Duração Go maior que 0, por exemplo `2h`. Antes do prazo da ordem, o executor mantém esta margem e entrega uma escrita não resolvida a uma decisão humana. |
| `EXECUTOR_SETTLE_WINDOW` | `1s` | Duração Go. Defina-a com pelo menos a latência assíncrona do seu ledger. |
| `EXECUTOR_ORPHAN_RECONCILE_WINDOW` | `48h` | Até quando, no passado, o executor procura operações em contas de bloqueio que ele não escreveu. |

## Listener de webhook

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `EXECUTOR_TRANSPORT` | `webhook` | Como os avisos de execução chegam ao executor. Esta página descreve `webhook`. |
| `EXECUTOR_HUB_WEBHOOK_ADDRESS` | `:9082` | Endereço de escuta do listener de webhook. |
| `EXECUTOR_HUB_WEBHOOK_PATH` | `/v1/webhooks/hub` | Rota do listener de webhook. Deve começar com `/`. |
| `EXECUTOR_HUB_WEBHOOK_SECRET` | **Obrigatório** | Secret de assinatura da assinatura do Streaming Hub. Sensível. |
| `EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS` | — | O secret anterior à última rotação. O listener aceita os dois secrets. Sensível. |
| `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC` | `300` | De `1` a `300`. O listener aceita uma entrega fora desta diferença de relógio, com um aviso no log. |
| `EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE` | **Obrigatório fora de `DEPLOYMENT_MODE=local`, a menos que o TLS termine antes** | Certificado de servidor do listener. Defina-o junto com a chave. |
| `EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE` | **Obrigatório com o certificado** | Chave privada desse certificado. Sensível. |
| `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED` | `false` | Defina como `true` quando o TLS termina na frente do listener. |
| `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS` | `5` | Número de tentativas para cada entrega aceita. Deve ser pelo menos 1 + `EXECUTOR_SETTLE_WINDOW` / `EXECUTOR_TICK_EVERY`, arredondado para cima. |

## Midaz

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | Superfície de CRM das instituições que não definem `crmMode`: `legacy` (o CRM autônomo do Midaz em `crmBaseUrl`) ou `embedded` (o CRM do ledger Midaz em `baseUrl`). |

O executor lê a conexão com o Midaz de cada instituição da sua configuração, não de variáveis de ambiente. [Operando o Lerian SISBAJUD executor](/pt/rails/sisbajud/sisbajud-executor-operations#institution-setup) a descreve.

## Streaming de eventos

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publica eventos. Com o HashiCorp Vault, uma rotação da chave de credenciais publica `kek.rotated`. O boot recusa `false` quando `STREAMING_BROKERS` está definido. |
| `STREAMING_BROKERS` | — | Lista de brokers Kafka separada por vírgulas. |
| `STREAMING_TLS_ENABLED` | **`true` em produção** | Conecta aos brokers por TLS. |
| `OUTBOX_ENABLED` | `true` | Caminho de entrega durável dos eventos. `STREAMING_ENABLED=true` o exige. |

<h2 id="values-that-must-match-the-mensageria">
  Valores que devem coincidir com a Mensageria
</h2>

* **`RESPONSE_DEADLINE_MARGIN`.** A Mensageria lê a mesma variável. Defina o mesmo valor nos dois componentes.
* **TLS mútuo.** Defina `MENSAGERIA_MTLS_ENABLED` com o mesmo valor de `SISBAJUD_EXECUTION_MTLS_ENABLED` na Mensageria. Com TLS mútuo ligado na Mensageria e desligado no executor, o handshake TLS falha.
* **Identidade do executor.** Na Mensageria, o cliente M2M em `MENSAGERIA_CLIENT_ID` tem o papel `br-sisbajud-executor-role`. `EXECUTOR_M2M_SUBJECT` é o `sub` do token desse cliente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.