> ## 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 source-available (ELv2). 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.
Todo produto Lerian compartilha um conjunto de blocos de configuração: postura de TLS, OpenTelemetry, autenticação do Access Manager, multi-tenancy, service discovery e streaming de eventos. A [referência de configuração do BYOC](/pt/reference/byoc-configuration) documenta esses blocos. Esta página foca no que é específico do ledger.
A consolidação já aconteceu. Você faz o deploy do serviço de **ledger** (rotas unificadas de onboarding + transaction), e o **CRM** e o **Fees** são compilados nesse mesmo processo de ledger. O binário do ledger lê as variáveis de CRM e Fees abaixo. O Tracer vive no mesmo repositório e é entregue como seu próprio serviço opcional. Os antigos componentes `onboarding`, `transaction` e `mdz` não existem mais como itens implantáveis separados. O Helm chart ainda 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](/pt/reference/health-and-readiness) para o contrato de probe.
| Superfície | Variável de porta | Padrão | Endpoints |
| --------------------------------------------------------------------------------- | -------------------------------- | ------ | -------------------------------- |
| HTTP do ledger (onboarding + transaction) | `SERVER_PORT` / `SERVER_ADDRESS` | `3002` | `/health`, `/readyz`, `/version` |
| HTTP do CRM (deployment standalone legado, desabilitado por padrão no Helm chart) | `SERVER_PORT` / `SERVER_ADDRESS` | `4003` | `/health`, `/readyz` |
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. 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 |
| `VERSION` | Tag de versão do serviço | varia | 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` | Intervalo máximo em meses para consultas de faixa de datas. A configuração de exemplo empacotada vem com `3`. | `1` | 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; forneç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 | `3000` | Não |
| `DB_{MODULE}_MAX_IDLE_CONNS` | Número máximo de conexões ociosas no pool | `3000` | 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 | `1000` (Fees `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` | Caminho do arquivo de credenciais do GCP para autenticação por IAM | — | Não |
## 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_OVERDRAFT_EVENTS_ENABLED` | Publica eventos de overdraft. Qualquer valor diferente de `false` — inclusive quando não definido — habilita a publicação; defina `false` explicitamente para desabilitar. A configuração de exemplo empacotada vem com `false`. | habilitado | Não |
| `AUDIT_LOG_ENABLED` | Acrescenta transações a uma exchange de log de auditoria. Qualquer valor diferente de `false` — inclusive quando não definido — habilita; defina `false` explicitamente para desabilitar. A configuração de exemplo empacotada vem com `false`. | habilitado | 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 | `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 reserve limites de gastos junto ao Tracer antes de fazer commit de uma transação. Deixe `TRACER_BASE_URL` sem definir para desabilitá-la.
| Variável | Descrição | Padrão | Obrigatório |
| ---------------------- | -------------------------------------------------------------------------------------------- | ------ | ----------- |
| `TRACER_BASE_URL` | URL do serviço do Tracer; defini-la habilita o cliente de reserva | — | Não |
| `TRACER_TIMEOUT_MS` | Prazo da chamada de reserva (milissegundos) | `250` | Não |
| `TRACER_TRANSPORT` | Transporte da reserva: `grpc` ou `rest` | `grpc` | Não |
| `TRACER_TLS_MODE` | Segurança do ponto de integração: `mesh` (padrão, TLS terminado pelo service mesh) ou `mtls` | `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`) | — | Se `mtls` |
Com `TRACER_BASE_URL` definida, o ponto de integração usa o transporte `grpc` padrão, a menos que você defina `TRACER_TRANSPORT=rest`. O transporte gRPC exige que o serviço Tracer exponha seu ponto de integração gRPC de reserva. Defina `TRACER_GRPC_PORT` no Tracer (veja [Variáveis de ambiente do Tracer](/pt/products/tracer/tracer-environment-variables)). Em `TRACER_TLS_MODE=mtls`, você deve definir os caminhos de certificado do cliente, chave e CA acima.
## 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 `hashicorp-vault`) | — | Não |
| `KMS_VAULT_AUTH_METHOD` | Método de autenticação do Vault: `token` ou `approle`. Use `approle` em `byoc`/`saas`. | `token` | Não |
| `KMS_VAULT_ROLE_ID` | ID do role do AppRole do Vault (quando `approle`) | — | Não |
| `KMS_VAULT_SECRET_ID` | ID do secret do AppRole do Vault (quando `approle`). Sensível. | — | Não |
## Backbone de configuração compartilhado
Os blocos a seguir são idênticos em todos os produtos Lerian. A [referência de configuração do BYOC](/pt/reference/byoc-configuration) os documenta por completo. Eles vêm desabilitados por padrão. Um deployment BYOC single-tenant pode ignorar todos os opcionais.
* **Autenticação do Access Manager**: `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_HOST`. Habilite em produção.
* **Multi-tenancy**: `MULTI_TENANT_*`. Desabilitado por padrão. Habilita a resolução de banco de dados por tenant.
* **Service discovery**: `SD_*` (Consul). Desabilitado por padrão.
* **Streaming de eventos**: `STREAMING_*` (produtor do lib-streaming). Desabilitado por padrão no ledger.
* **OpenTelemetry**: `ENABLE_TELEMETRY`, `OTEL_*`. A telemetria é OTLP push.