> ## 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 usadas para configurar o serviço de ledger do Midaz, organizadas por categoria.
Esta referência lista as variáveis de ambiente usadas para configurar o **serviço de ledger do Midaz** — o motor de dupla entrada de código-fonte disponível (ELv2) que atende às APIs de onboarding e de transação em uma única porta. Você as define no momento da implantação, por valores Helm, Docker Compose ou pelo ambiente do seu orquestrador. Variáveis marcadas como obrigatórias fazem o servidor falhar na inicialização se não forem definidas.
Para os blocos de configuração que todo produto Lerian compartilha — postura de TLS, OpenTelemetry, autenticação do Access Manager, multi-tenancy, service discovery e streaming de eventos — veja a [referência de configuração BYOC](/pt/reference/byoc-configuration). Esta página foca no que é distintivo do ledger.
O Midaz está em meio a uma consolidação. O que você implanta hoje é o serviço de **ledger** (rotas unificadas de onboarding + transação) mais um serviço **CRM** autônomo. O layout consolidado de binário único — que dobra CRM e Fees dentro do processo do ledger e traz o Tracer para o mesmo repositório — está em processo de rollout. As variáveis de CRM e Fees abaixo aplicam-se ao serviço CRM autônomo hoje, e ao processo do ledger assim que a consolidação chegar ao seu ambiente. Os antigos componentes `onboarding`, `transaction` e `mdz` não existem mais como implantáveis separados.
## Portas e endpoints de saúde
O ledger roda um único processo HTTP. Veja a [referência de saúde e prontidão](/pt/reference/health-and-readiness) para o contrato de sondas.
| Superfície | Variável de porta | Padrão | Endpoints |
| ---------------------------------------------------------- | -------------------------------- | ------ | -------------------------------- |
| HTTP do ledger (onboarding + transação) | `SERVER_PORT` / `SERVER_ADDRESS` | `3002` | `/health`, `/readyz`, `/version` |
| HTTP do CRM (serviço autônomo, layout entregue atualmente) | `SERVER_PORT` / `SERVER_ADDRESS` | `4003` | `/health`, `/readyz` |
O ledger usa push OTLP para telemetria e não expõe um endpoint `/metrics` para scraping.
## Implantação e TLS
| Variável | Descrição | Padrão | Obrigatória |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- |
| `DEPLOYMENT_MODE` | Sabor de implantação: `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 alertado em vez de imposto. Também marca a resposta de `/readyz`. | `local` | Não |
| `ALLOW_INSECURE_TLS` | Ignora a imposição de TLS por conexão nas DSNs de infraestrutura. Deixe sem definir ou `false` em produção; defina `true` apenas para infraestrutura local em texto puro. | `false` | Não |
## Aplicação
| Variável | Descrição | Padrão | Obrigatória |
| --------------------------------- | ----------------------------------------------------------------------- | ------------- | ----------- |
| `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 dos logs: `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 por faixa de datas | `3` | 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 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ória |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- |
| `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 pelo seu cofre de segredos. | — | 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 mais forte em produção. | `disable` | Não |
| `DB_{MODULE}_MAX_OPEN_CONNS` | Máximo de conexões abertas no pool | `3000` | Não |
| `DB_{MODULE}_MAX_IDLE_CONNS` | Máximo de conexões ociosas no pool | `3000` | Não |
## Document store (MongoDB)
Com namespace por módulo: `MONGO_ONBOARDING_*`, `MONGO_TRANSACTION_*` e — no binário consolidado — `MONGO_CRM_*` e `MONGO_FEES_*`. Todos compartilham um formato; substitua `{NS}` pelo namespace. Eles podem apontar para uma única implantação MongoDB (bancos de dados lógicos separados) ou para hosts dedicados.
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------- | ----------------------------------------------------------------------------- | ------------------- | ----------- |
| `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 PEM codificado em Base64 para TLS (por exemplo AWS DocumentDB) | — | Não |
| `MONGO_{NS}_PARAMETERS` | Parâmetros extras da string de conexão | — | Não |
## Cache (Redis / Valkey)
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------- | --------------------------------------------------------------- | ------- | ----------- |
| `REDIS_HOST` | Host e porta do Redis/Valkey | — | Sim |
| `REDIS_PASSWORD` | Senha de autenticação. Sensível. | — | Não |
| `REDIS_TLS` | Ativa o TLS para a conexão | `false` | Não |
| `REDIS_CA_CERT` | Certificado CA 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 (implantações com Sentinel) | — | Não |
| `REDIS_USE_GCP_IAM` | Autentica no GCP Memorystore com IAM em vez de senha | `false` | Não |
| `REDIS_SERVICE_ACCOUNT` | Conta de serviço GCP para autenticação IAM | — | Não |
| `GOOGLE_APPLICATION_CREDENTIALS` | Caminho para o arquivo de credenciais GCP para autenticação IAM | — | Não |
## Message broker (RabbitMQ)
Usado pelo módulo de transação para operações de saldo e fan-out de eventos.
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------------- | --------------------------------------------------------------- | ------- | ----------- |
| `RABBITMQ_HOST` | Host do broker | — | Sim |
| `RABBITMQ_PORT_AMQP` | Porta AMQP | — | Sim |
| `RABBITMQ_PORT_HOST` | Porta de gerenciamento/HTTP | — | Não |
| `RABBITMQ_URI` | Esquema de conexão: `amqp` ou `amqps`. Use `amqps` em produção. | `amqp` | Não |
| `RABBITMQ_DEFAULT_USER` | Usuário publicador | — | Sim |
| `RABBITMQ_DEFAULT_PASS` | Senha do publicador. Sensível. | — | Sim |
| `RABBITMQ_CONSUMER_USER` | Usuário consumidor | — | Sim |
| `RABBITMQ_CONSUMER_PASS` | Senha do consumidor. Sensível. | — | Sim |
| `RABBITMQ_VHOST` | Virtual host | `/` | Não |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Concorrência de consumidores | `5` | Não |
| `RABBITMQ_PREFETCH` | Contagem de prefetch do consumidor | `10` | Não |
| `RABBITMQ_TRANSACTION_ASYNC` | Registra transações de forma assíncrona através do broker | `false` | Não |
| `RABBITMQ_TRANSACTION_EVENTS_ENABLED` | Publica eventos de transação | `false` | Não |
| `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` | Publica eventos de overdraft | `false` | Não |
| `AUDIT_LOG_ENABLED` | Anexa transações a um exchange de log de auditoria | `false` | Não |
## Throughput
| Variável | Descrição | Padrão | Obrigatória |
| ----------------------------------- | ---------------------------------------------------------------------- | ------ | ----------- |
| `BULK_RECORDER_ENABLED` | Faz o batch das escritas de transação para ingestão de alto throughput | `true` | Não |
| `BULK_RECORDER_SIZE` | Gatilho por tamanho do batch (`0` = disparo por tamanho desligado) | `0` | Não |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS` | Intervalo de flush do recorder em batch (milissegundos) | `100` | Não |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Máximo de linhas por insert em batch | `1000` | Não |
## Integração com o Tracer
Seam opcional que permite ao ledger reservar limites de gasto no Tracer antes de confirmar uma transação. Deixe `TRACER_BASE_URL` sem definir para desativar.
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------- | ----------------------------------------------------------------------------- | ------ | ----------- |
| `TRACER_BASE_URL` | URL do serviço Tracer; defini-la ativa 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 seam: `mesh` (padrão, TLS terminado pelo service mesh) ou `mtls` | `mesh` | Não |
| `TRACER_TLS_CERT_FILE` | Caminho do PEM do certificado de cliente (quando `mtls`) | — | Se `mtls` |
| `TRACER_TLS_KEY_FILE` | Caminho do PEM da chave privada de cliente (quando `mtls`). Sensível. | — | Se `mtls` |
| `TRACER_TLS_CA_FILE` | Caminho do PEM do certificado CA (quando `mtls`) | — | Se `mtls` |
Com `TRACER_BASE_URL` definida, o seam 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 seam gRPC de reserva — defina `TRACER_GRPC_PORT` no Tracer (consulte [Variáveis de ambiente do Tracer](/pt/tracer/tracer-environment-variables)). Com `TRACER_TLS_MODE=mtls`, os caminhos do certificado de cliente, da chave e da CA acima são obrigatórios.
## CRM e Fees
Estas variáveis aplicam-se ao serviço CRM autônomo hoje, e ao processo do ledger assim que CRM e Fees se integrarem a ele. Elas protegem os PII dos titulares de conta e configuram o backend de criptografia de campos.
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------------- | ----------------------------------------------------------------------------------------------- | ------- | ----------- |
| `LCRYPTO_HASH_SECRET_KEY` | Chave de hashing de 64 hex para os PII do titular. Sensível — gere um valor único por ambiente. | — | Sim (CRM) |
| `LCRYPTO_ENCRYPT_SECRET_KEY` | Chave de criptografia de 64 hex para os 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` | Role ID do AppRole do Vault (quando `approle`) | — | Não |
| `KMS_VAULT_SECRET_ID` | Secret ID do AppRole do Vault (quando `approle`). Sensível. | — | Não |
| `DEFAULT_CURRENCY` | Moeda de fallback para tarifas (ISO 4217) | `USD` | Não |
## Base de configuração compartilhada
Os blocos a seguir são idênticos entre os produtos Lerian e estão documentados por completo na [referência de configuração BYOC](/pt/reference/byoc-configuration). Eles vêm desativados; uma implantação BYOC single-tenant pode ignorar todos os opcionais.
* **Autenticação do Access Manager** — `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_HOST`. Ative em produção.
* **Multi-tenancy** — `MULTI_TENANT_*`. Desativado por padrão; ativa a resolução de banco de dados por tenant.
* **Service discovery** — `SD_*` (Consul). Desativado por padrão.
* **Streaming de eventos** — `STREAMING_*` (produtor lib-streaming). Desativado por padrão no ledger.
* **OpenTelemetry** — `ENABLE_TELEMETRY`, `OTEL_*`. A telemetria é push OTLP.