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

> Referência das variáveis de ambiente do serviço de ledger do Midaz: portas, TLS, modo de deploy e configurações de CRM ou Fees para as APIs de onboarding e transação.

Esta referência lista as variáveis de ambiente que configuram o **serviço de ledger do Midaz**. O Midaz é o mecanismo de partidas dobradas. Ele atende as APIs de onboarding e transação em uma única porta. Você define essas variáveis no momento do deploy, por meio de valores do Helm, do Docker Compose ou do ambiente do seu orquestrador. Uma variável obrigatória que você não define faz o servidor falhar na inicialização. Um valor que o servidor não consegue ler também faz o servidor falhar na inicialização, e o erro nomeia a variável. Um booleano aceita apenas `true` ou `false`. Um número precisa ser inteiro. Uma duração precisa de uma unidade, como `12s`.

Todo produto Lerian compartilha um conjunto de blocos de configuração: postura de TLS, OpenTelemetry, autenticação do Access Manager, service discovery e streaming de eventos. A [referência de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) documenta esses blocos. Esta página foca no que é específico do ledger.

> [!NOTE]
>
> Você faz o deploy do serviço de **ledger**. Ele atende as rotas de onboarding e transaction, e o **CRM** e o **Fees** rodam no mesmo processo. O ledger lê as variáveis de CRM e Fees abaixo. O Tracer é entregue como seu próprio serviço opcional. O Helm chart também traz um deployment `crm` standalone legado, desabilitado por padrão.

## Portas e endpoints de saúde

O ledger executa um único processo HTTP. Consulte a [referência de saúde e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato de probe.

| Superfície | Variável de porta | Padrão | Endpoints |
| - | - | - | - |
| HTTP do ledger (onboarding + transaction) | `SERVER_ADDRESS` | `:3002` | `/health`, `/readyz`, `/version` |

O ledger usa OTLP push para telemetria e não expõe um endpoint de scrape `/metrics`.

## Deploy e TLS

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Tipo de deploy: `local`, `byoc` ou `saas`. Em `saas`, o TLS é obrigatório para toda conexão de dependência e o servidor se recusa a iniciar sem ele. Em `byoc`, o TLS é recomendado e gera aviso, mas não é aplicado. Em `saas`, o servidor também se recusa a iniciar quando `PLUGIN_AUTH_ENABLED` não é `true`. Também marca a resposta de `/readyz`. | `local` | Não |
| `ALLOW_INSECURE_TLS` | Contorna a aplicação de TLS por conexão em DSNs de infraestrutura. Deixe sem definir ou como `false` em produção; defina `true` apenas para infraestrutura local em texto plano. | `false` | Não |

## Aplicação

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENV_NAME` | Rótulo do ambiente (por exemplo, `development`, `staging`, `production`) | `development` | Não |
| `LOG_LEVEL` | Verbosidade do log: `debug`, `info`, `warn` ou `error` | `debug` | Não |
| `MAX_PAGINATION_LIMIT` | Tamanho máximo de página aceito pelos endpoints de listagem | `100` | Não |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Janela padrão em meses para listagens de transações e operações quando nem a data inicial nem a final são informadas. | `1` | Não |
| `TRANSACTION_BATCH_MAX_SIZE` | Número máximo de transações em uma requisição de lote atômico. Aceita de `1` a `50`. Qualquer outro valor para o servidor na inicialização. | `10` | Não |
| `OPENAPI_DOCS_ENABLED` | Serve a spec OpenAPI 3.1 em `/openapi.json` e `/openapi.yaml`, e a documentação interativa em `/docs` | `false` | Não |
| `SHUTDOWN_DRAIN_DELAY` | Espera entre marcar o `/readyz` como indisponível no desligamento e fechar o servidor HTTP, como duração Go (por exemplo `12s`). `0` pula a espera. Um valor acima de `20s` usa `20s`. | `12s` | Não |

## Banco de dados (PostgreSQL)

O ledger mantém dois bancos de dados lógicos (`onboarding` e `transaction`), cada um com um bloco de conexão primário e um de réplica. As variáveis compartilham um único formato. Substitua `{MODULE}` por `ONBOARDING` ou `TRANSACTION`. As variáveis de réplica carregam um infixo `_REPLICA_` (por exemplo, `DB_ONBOARDING_REPLICA_HOST`).

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `DB_{MODULE}_HOST` | Host primário do PostgreSQL | — | Sim |
| `DB_{MODULE}_PORT` | Porta do PostgreSQL | — | Sim |
| `DB_{MODULE}_USER` | Usuário do banco de dados | — | Sim |
| `DB_{MODULE}_PASSWORD` | Senha do banco de dados. Sensível. Não faça commit dela. Forneça-a por meio do seu secret store. | — | Sim |
| `DB_{MODULE}_NAME` | Nome do banco de dados | `onboarding` / `transaction` | Sim |
| `DB_{MODULE}_SSLMODE` | Modo SSL do libpq: `disable`, `require`, `verify-ca` ou `verify-full`. Use `require` ou um modo mais forte em produção. | `disable` | Não |
| `DB_{MODULE}_MAX_OPEN_CONNS` | Número máximo de conexões abertas no pool. Sem valor ou `0` usa o padrão. | `25` | Não |
| `DB_{MODULE}_MAX_IDLE_CONNS` | Número máximo de conexões ociosas no pool. Sem valor ou `0` usa o padrão. | `10` | Não |
| `DB_TRANSACTION_ROUTE_TX_READS_TO_PRIMARY` | Envia as leituras do fluxo de transação ao primário, não à réplica. `false` desativa. | `true` | Não |

## Armazenamento de documentos (MongoDB)

As variáveis do MongoDB usam um namespace por módulo: `MONGO_ONBOARDING_*`, `MONGO_TRANSACTION_*` e, no binário consolidado, `MONGO_CRM_*` e `MONGO_FEES_*`. Todas compartilham um único formato. Substitua `{NS}` pelo namespace. Elas podem apontar para um único deployment do MongoDB (bancos de dados lógicos separados) ou para hosts dedicados.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `MONGO_{NS}_HOST` | Host do MongoDB | — | Sim |
| `MONGO_{NS}_PORT` | Porta do MongoDB | — | Sim |
| `MONGO_{NS}_USER` | Usuário do banco de dados | — | Sim |
| `MONGO_{NS}_PASSWORD` | Senha do banco de dados. Sensível. | — | Sim |
| `MONGO_{NS}_NAME` | Nome do banco de dados | nome do namespace | Sim |
| `MONGO_{NS}_URI` | Esquema de conexão: `mongodb` ou `mongodb+srv` | `mongodb` | Não |
| `MONGO_{NS}_MAX_POOL_SIZE` | Tamanho máximo do pool de conexões | `100` | Não |
| `MONGO_{NS}_TLS_CA_CERT` | Certificado CA em PEM codificado em Base64 para TLS (por exemplo, AWS DocumentDB) | — | Não |
| `MONGO_{NS}_PARAMETERS` | Parâmetros extras da connection string | — | Não |

## Cache (Redis / Valkey)

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `REDIS_HOST` | Host e porta do Redis/Valkey | — | Sim |
| `REDIS_PASSWORD` | Senha de autenticação. Sensível. | — | Não |
| `REDIS_TLS` | Habilita o TLS para a conexão | `false` | Não |
| `REDIS_CA_CERT` | Certificado CA em PEM codificado em Base64 para TLS | — | Não |
| `REDIS_DB` | Índice do banco de dados lógico | `0` | Não |
| `REDIS_PROTOCOL` | Versão do protocolo RESP | `3` | Não |
| `REDIS_POOL_SIZE` | Tamanho do pool de conexões | `10` | Não |
| `REDIS_MASTER_NAME` | Nome do master do Sentinel (deployments com Sentinel) | — | Não |
| `REDIS_USE_GCP_IAM` | Autentica no GCP Memorystore com IAM em vez de senha | `false` | Não |
| `REDIS_SERVICE_ACCOUNT` | Service account do GCP para autenticação por IAM | — | Não |
| `GOOGLE_APPLICATION_CREDENTIALS` | Credenciais da service account do GCP codificadas em Base64 para autenticação por IAM | — | Quando `REDIS_USE_GCP_IAM=true` |

## Broker de mensagens (RabbitMQ)

O pipeline interno assíncrono de operações de saldo usa o RabbitMQ quando `RABBITMQ_TRANSACTION_ASYNC=true`. O RabbitMQ também carrega exchanges legadas de saída selecionadas.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `RABBITMQ_HOST` | Host do broker | — | Sim |
| `RABBITMQ_PORT_HOST` | **Porta AMQP** usada para se conectar ao broker. Apesar do nome, esta é a porta que a connection string usa (`3003` na infraestrutura empacotada). | — | Sim |
| `RABBITMQ_PORT_AMQP` | **Porta de gerenciamento/HTTP** informada na conexão de health check (`3004` na infraestrutura empacotada). Apesar do nome, não é usada para conexão AMQP. | — | Não |
| `RABBITMQ_URI` | Esquema de conexão: `amqp` ou `amqps`. Use `amqps` em produção. | `amqp` | Não |
| `RABBITMQ_DEFAULT_USER` | Usuário do publicador | — | Sim |
| `RABBITMQ_DEFAULT_PASS` | Senha do publicador. Sensível. | — | Sim |
| `RABBITMQ_CONSUMER_USER` | Usuário do consumidor | — | Sim |
| `RABBITMQ_CONSUMER_PASS` | Senha do consumidor. Sensível. | — | Sim |
| `RABBITMQ_VHOST` | Host virtual | `/` | Não |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Concorrência de consumidores | `5` | Não |
| `RABBITMQ_NUMBERS_OF_PREFETCH` | Contagem de prefetch dos consumidores | `10` | Não |
| `RABBITMQ_TRANSACTION_ASYNC` | Registra transações de forma assíncrona por meio do broker | `false` | Não |
| `RABBITMQ_OPERATION_TIMEOUT` | Espera máxima pela confirmação de uma publicação pelo broker, como duração Go (por exemplo `5s`). | `5s` | Não |
| `RABBITMQ_HEALTH_CHECK_URL` | URL de gerenciamento do RabbitMQ que o `/readyz` verifica. A verificação usa as credenciais de `RABBITMQ_DEFAULT_USER`, então esse usuário precisa de acesso à API de gerenciamento. Um valor vazio pula a verificação. O Helm chart substitui um valor vazio pela URL de gerenciamento do RabbitMQ. | — | Não |
| `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` | Publica os eventos de overdraft no RabbitMQ e no streaming. `false` desativa os dois. Consulte [Overdraft de saldo](https://docs.lerian.studio/pt/products/midaz/balance-overdraft.md). | `true` | Não |
| `AUDIT_LOG_ENABLED` | Publica mensagens de auditoria de transações no RabbitMQ. Consulte [Auditabilidade](https://docs.lerian.studio/pt/products/midaz/auditability.md). | `false` | Não |

## Throughput

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `BULK_RECORDER_ENABLED` | Agrupa em lote a gravação de transações para ingestão de alto throughput. Só tem efeito quando `RABBITMQ_TRANSACTION_ASYNC=true`. | `true` | Não |
| `BULK_RECORDER_SIZE` | Gatilho de tamanho do lote. Quando não definida, o Midaz a deriva de `RABBITMQ_NUMBERS_OF_WORKERS` × `RABBITMQ_NUMBERS_OF_PREFETCH` (50 com os valores padrão de worker e prefetch). | workers × prefetch | Não |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS` | Intervalo de flush do gravador em lote (milissegundos) | `100` | Não |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Número máximo de linhas por insert em lote | `1000` | Não |

## Integração com o Tracer

O ponto de integração opcional permite que o ledger verifique uma transação com o Tracer antes de fazer commit dela. Deixe `TRACER_BASE_URL` sem definir para desabilitá-la.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `TRACER_BASE_URL` | Endereço do ponto de integração gRPC do Tracer, `host:4021` (a `TRACER_GRPC_PORT` do Tracer). Defini-la habilita o cliente de reserva. | — | Não |
| `TRACER_TIMEOUT_MS` | Prazo da chamada de reserva (milissegundos) | `250` | Não |
| `TRACER_TLS_MODE` | Segurança do ponto de integração: `mesh` (padrão, TLS terminado pelo service mesh), `mtls` ou `server` | `mesh` | Não |
| `TRACER_TLS_CERT_FILE` | Caminho do certificado PEM do cliente (quando `mtls`) | — | Se `mtls` |
| `TRACER_TLS_KEY_FILE` | Caminho da chave privada PEM do cliente (quando `mtls`). Sensível. | — | Se `mtls` |
| `TRACER_TLS_CA_FILE` | Caminho do certificado CA em PEM (quando `mtls` ou `server`) | — | Se `mtls` ou `server` |
| `TRACER_M2M_CLIENT_ID` | Lida com `PLUGIN_AUTH_ENABLED=true`. | — | Obrigatória quando `TRACER_BASE_URL` está definida e `PLUGIN_AUTH_ENABLED=true`. |
| `TRACER_M2M_CLIENT_SECRET` | Lida com `PLUGIN_AUTH_ENABLED=true`. Sensível. | — | Obrigatória quando `TRACER_BASE_URL` está definida e `PLUGIN_AUTH_ENABLED=true`. |
| `TRACER_M2M_WAIT_TIMEOUT_MS` | Lida apenas com `PLUGIN_AUTH_ENABLED=true`. Aceita de `1` a `5000` (milissegundos). | `3000` | Não |
| `TRACER_API_KEY` | Lida com `PLUGIN_AUTH_ENABLED=false`. Quando `TRACER_BASE_URL` está definida, o ledger não inicia se você também definir `PLUGIN_AUTH_ENABLED=true`. O Tracer a aceita apenas com `API_KEY_ENABLED=true` e `PLUGIN_AUTH_ENABLED=false`. Sensível. | — | Não |

## CRM e Fees

O processo do ledger lê essas variáveis, porque o CRM e o Fees são compilados no binário do ledger. Elas protegem os PII do titular da conta e configuram o backend de criptografia de campos.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `LCRYPTO_HASH_SECRET_KEY` | Chave de hash de 64 hex para o PII do titular. Sensível. Gere um valor único por ambiente. | — | Sim (CRM) |
| `LCRYPTO_ENCRYPT_SECRET_KEY` | Chave de criptografia de 64 hex para o PII do titular. Sensível. | — | Sim (CRM) |
| `KMS_VENDOR` | Backend de criptografia de campos: `none` ou `hashicorp-vault` | `none` | Não |
| `KMS_VAULT_ADDR` | Endereço do Vault | — | Quando `KMS_VENDOR=hashicorp-vault` |
| `KMS_VAULT_AUTH_METHOD` | Método de autenticação do Vault: `token` ou `approle`. Use `token` apenas em `local`; use `approle` em `byoc`/`saas`. | — | Quando `KMS_VENDOR=hashicorp-vault` |
| `KMS_VAULT_ROLE_ID` | ID do role do AppRole do Vault | — | Quando `KMS_VAULT_AUTH_METHOD=approle` |
| `KMS_VAULT_SECRET_ID` | ID do secret do AppRole do Vault. Sensível. | — | Quando `KMS_VAULT_AUTH_METHOD=approle` |

## Configuração compartilhada entre os produtos Lerian

Os blocos a seguir são idênticos em todos os produtos Lerian. A [referência de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) os documenta por completo. Eles vêm desabilitados por padrão. Um deployment BYOC pode ignorar todos os opcionais.

* **Autenticação do Access Manager**: `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_HOST`. Habilite em produção.
* **Service discovery**: `SD_*` (Consul). Desabilitado por padrão.
* **Streaming de eventos**: `STREAMING_*`. Desabilitado por padrão no ledger.
* **OpenTelemetry**: `ENABLE_TELEMETRY`, `OTEL_*`. A telemetria é OTLP push.


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