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. 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. Um valor que o servidor não consegue ler também faz o servidor falhar na inicialização, e o erro nomeia a variável. Um booleano aceita apenas true ou false. Um número precisa ser inteiro. Uma duração precisa de uma unidade, como 12s. Todo produto Lerian compartilha um conjunto de blocos de configuração: postura de TLS, OpenTelemetry, autenticação do Access Manager, 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.

Você faz o deploy do serviço de ledger. Ele atende as rotas de onboarding e transaction, e o CRM e o Fees rodam no mesmo processo. O ledger lê as variáveis de CRM e Fees abaixo. O Tracer é entregue como seu próprio serviço opcional. O Helm chart também 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_ADDRESS`	`:3002`	`/health`, `/readyz`, `/version`

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. Em `saas`, o servidor também se recusa a iniciar quando `PLUGIN_AUTH_ENABLED` não é `true`. 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
`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`	Janela padrão em meses para listagens de transações e operações quando nem a data inicial nem a final são informadas.	`1`	Não
`TRANSACTION_BATCH_MAX_SIZE`	Número máximo de transações em uma requisição de lote atômico. Aceita de `1` a `50`. Qualquer outro valor para o servidor na inicialização.	`10`	Não
`OPENAPI_DOCS_ENABLED`	Serve a spec OpenAPI 3.1 em `/openapi.json` e `/openapi.yaml`, e a documentação interativa em `/docs`	`false`	Não
`SHUTDOWN_DRAIN_DELAY`	Espera entre marcar o `/readyz` como indisponível no desligamento e fechar o servidor HTTP, como duração Go (por exemplo `12s`). `0` pula a espera. Um valor acima de `20s` usa `20s`.	`12s`	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 dela. Forneça-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. Sem valor ou `0` usa o padrão.	`25`	Não
`DB_{MODULE}_MAX_IDLE_CONNS`	Número máximo de conexões ociosas no pool. Sem valor ou `0` usa o padrão.	`10`	Não
`DB_TRANSACTION_ROUTE_TX_READS_TO_PRIMARY`	Envia as leituras do fluxo de transação ao primário, não à réplica. `false` desativa.	`true`	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	`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`	Credenciais da service account do GCP codificadas em Base64 para autenticação por IAM	—	Quando `REDIS_USE_GCP_IAM=true`

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_OPERATION_TIMEOUT`	Espera máxima pela confirmação de uma publicação pelo broker, como duração Go (por exemplo `5s`).	`5s`	Não
`RABBITMQ_HEALTH_CHECK_URL`	URL de gerenciamento do RabbitMQ que o `/readyz` verifica. A verificação usa as credenciais de `RABBITMQ_DEFAULT_USER`, então esse usuário precisa de acesso à API de gerenciamento. Um valor vazio pula a verificação. O Helm chart substitui um valor vazio pela URL de gerenciamento do RabbitMQ.	—	Não
`RABBITMQ_OVERDRAFT_EVENTS_ENABLED`	Publica os eventos de overdraft no RabbitMQ e no streaming. `false` desativa os dois. Consulte Overdraft de saldo.	`true`	Não
`AUDIT_LOG_ENABLED`	Publica mensagens de auditoria de transações no RabbitMQ. Consulte Auditabilidade.	`false`	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. Só tem efeito quando `RABBITMQ_TRANSACTION_ASYNC=true`.	`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 verifique uma transação com o Tracer antes de fazer commit dela. Deixe TRACER_BASE_URL sem definir para desabilitá-la.

Variável	Descrição	Padrão	Obrigatório
`TRACER_BASE_URL`	Endereço do ponto de integração gRPC do Tracer, `host:4021` (a `TRACER_GRPC_PORT` do Tracer). Defini-la habilita o cliente de reserva.	—	Não
`TRACER_TIMEOUT_MS`	Prazo da chamada de reserva (milissegundos)	`250`	Não
`TRACER_TLS_MODE`	Segurança do ponto de integração: `mesh` (padrão, TLS terminado pelo service mesh), `mtls` ou `server`	`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` ou `server`)	—	Se `mtls` ou `server`
`TRACER_M2M_CLIENT_ID`	Lida com `PLUGIN_AUTH_ENABLED=true`.	—	Obrigatória quando `TRACER_BASE_URL` está definida e `PLUGIN_AUTH_ENABLED=true`.
`TRACER_M2M_CLIENT_SECRET`	Lida com `PLUGIN_AUTH_ENABLED=true`. Sensível.	—	Obrigatória quando `TRACER_BASE_URL` está definida e `PLUGIN_AUTH_ENABLED=true`.
`TRACER_M2M_WAIT_TIMEOUT_MS`	Lida apenas com `PLUGIN_AUTH_ENABLED=true`. Aceita de `1` a `5000` (milissegundos).	`3000`	Não
`TRACER_API_KEY`	Lida com `PLUGIN_AUTH_ENABLED=false`. Quando `TRACER_BASE_URL` está definida, o ledger não inicia se você também definir `PLUGIN_AUTH_ENABLED=true`. O Tracer a aceita apenas com `API_KEY_ENABLED=true` e `PLUGIN_AUTH_ENABLED=false`. Sensível.	—	Não

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 `KMS_VENDOR=hashicorp-vault`
`KMS_VAULT_AUTH_METHOD`	Método de autenticação do Vault: `token` ou `approle`. Use `token` apenas em `local`; use `approle` em `byoc`/`saas`.	—	Quando `KMS_VENDOR=hashicorp-vault`
`KMS_VAULT_ROLE_ID`	ID do role do AppRole do Vault	—	Quando `KMS_VAULT_AUTH_METHOD=approle`
`KMS_VAULT_SECRET_ID`	ID do secret do AppRole do Vault. Sensível.	—	Quando `KMS_VAULT_AUTH_METHOD=approle`

Configuração compartilhada entre os produtos Lerian

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 pode ignorar todos os opcionais.

Autenticação do Access Manager: PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_HOST. Habilite em produção.
Service discovery: SD_* (Consul). Desabilitado por padrão.
Streaming de eventos: 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

​Configuração compartilhada entre os produtos Lerian

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

Configuração compartilhada entre os produtos Lerian