Variáveis de ambiente

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

​Portas e endpoints de saúde

​Implantação e TLS

​Aplicação

​Banco de dados (PostgreSQL)

​Document store (MongoDB)

​Cache (Redis / Valkey)

​Message broker (RabbitMQ)

​Throughput

​Integração com o Tracer

​CRM e Fees

​Base de configuração compartilhada

Portas e endpoints de saúde

Implantação e TLS

Aplicação

Banco de dados (PostgreSQL)

Document store (MongoDB)

Cache (Redis / Valkey)

Message broker (RabbitMQ)

Throughput

Integração com o Tracer

CRM e Fees

Base de configuração compartilhada