Variáveis de ambiente

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

​Portas e endpoints de saúde

​Deploy e TLS

​Aplicação

​Banco de dados (PostgreSQL)

​Armazenamento de documentos (MongoDB)

​Cache (Redis / Valkey)

​Broker de mensagens (RabbitMQ)

​Throughput

​Integração com o Tracer

​CRM e Fees

​Backbone de configuração compartilhado

Portas e endpoints de saúde

Deploy e TLS

Aplicação

Banco de dados (PostgreSQL)

Armazenamento de documentos (MongoDB)

Cache (Redis / Valkey)

Broker de mensagens (RabbitMQ)

Throughput

Integração com o Tracer

CRM e Fees

Backbone de configuração compartilhado