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 motor de dupla entrada de código-fonte disponível (ELv2). Ele atende às APIs de onboarding e de transação em uma única porta. Você define estas variáveis no momento da implantação, por valores Helm, Docker Compose ou pelo 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 BYOC documenta esses blocos. Esta página foca no que é distintivo do ledger.

A consolidação já aconteceu. Você implanta o serviço de ledger (rotas unificadas de onboarding + transação), e CRM e Fees são compilados dentro desse mesmo processo do ledger — o binário do ledger lê as variáveis de CRM e Fees abaixo. O Tracer vive no mesmo repositório e é implantado como serviço opcional próprio. Os antigos componentes onboarding, transaction e mdz não existem mais como implantáveis separados. O chart do Helm ainda traz um deployment crm autônomo legado, desabilitado por padrão.

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 (deployment autônomo legado, desabilitado por padrão no chart do Helm)	`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. A configuração de exemplo incluída define `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 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)

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 formato. Substitua {NS} pelo namespace. Elas 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)

O pipeline interno assíncrono de operações de saldo usa o RabbitMQ quando RABBITMQ_TRANSACTION_ASYNC=true; o RabbitMQ também transporta exchanges legados de saída selecionados.

Variável	Descrição	Padrão	Obrigatória
`RABBITMQ_HOST`	Host do broker	—	Sim
`RABBITMQ_PORT_HOST`	Porta AMQP usada para conectar ao broker. Apesar do nome, é esta a porta que a string de conexão 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 conectar via 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 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_NUMBERS_OF_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_OVERDRAFT_EVENTS_ENABLED`	Publica eventos de overdraft. Qualquer valor diferente de `false` — inclusive não definir — habilita a publicação; defina `false` explicitamente para desabilitar. A configuração de exemplo incluída define `false`.	habilitado	Não
`AUDIT_LOG_ENABLED`	Anexa transações a um exchange de log de auditoria. Qualquer valor diferente de `false` — inclusive não definir — o habilita; defina `false` explicitamente para desabilitar. A configuração de exemplo incluída define `false`.	habilitado	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. Quando não definida, o Midaz a deriva de `RABBITMQ_NUMBERS_OF_WORKERS` × `RABBITMQ_NUMBERS_OF_PREFETCH` (50 com os valores padrão de workers e prefetch).	workers × prefetch	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

O seam opcional permite ao ledger reservar limites de gasto no Tracer antes de confirmar uma transação. Deixe TRACER_BASE_URL sem definir para desativá-lo.

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, você deve definir os caminhos do certificado de cliente, da chave e da CA acima.

CRM e Fees

O processo do ledger lê estas variáveis — CRM e Fees são compilados dentro do binário do ledger. 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

Base de configuração compartilhada

Os blocos a seguir são idênticos entre os produtos Lerian. A referência de configuração BYOC os documenta por completo. 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