Environment variables

This reference lists the environment variables used to configure the Midaz ledger service — the source-available (ELv2) double-entry engine that serves the onboarding and transaction APIs on a single port. You set these at deploy time, through Helm values, Docker Compose, or your orchestrator’s environment. Variables marked as required cause the server to fail on startup if not set. For the configuration blocks that every Lerian product shares — TLS posture, OpenTelemetry, Access Manager authentication, multi-tenancy, service discovery, and event streaming — see the BYOC configuration reference. This page focuses on what is distinctive to the ledger.

Midaz is mid-consolidation. What you deploy today is the ledger service (unified onboarding + transaction routes) plus a standalone CRM service. The consolidated single-binary layout — which folds CRM and Fees into the ledger process and pulls Tracer into the same repository — is rolling out. The CRM and Fees variables below apply to the standalone CRM service today, and to the ledger process once consolidation lands in your environment. The former onboarding, transaction, and mdz components no longer exist as separate deployables.

Ports and health endpoints

The ledger runs one HTTP process. See the health and readiness reference for the probe contract.

Surface	Port variable	Default	Endpoints
Ledger HTTP (onboarding + transaction)	`SERVER_PORT` / `SERVER_ADDRESS`	`3002`	`/health`, `/readyz`, `/version`
CRM HTTP (standalone service, current shipped layout)	`SERVER_PORT` / `SERVER_ADDRESS`	`4003`	`/health`, `/readyz`

The ledger uses OTLP push for telemetry and does not expose a /metrics scrape endpoint.

Deployment and TLS

Variable	Description	Default	Required
`DEPLOYMENT_MODE`	Deployment flavor: `local`, `byoc`, or `saas`. In `saas`, TLS is mandatory for every dependency connection and the server refuses to start without it. In `byoc`, TLS is recommended and warned-on rather than enforced. Also tags the `/readyz` response.	`local`	No
`ALLOW_INSECURE_TLS`	Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or `false` in production; set `true` only for local plaintext infrastructure.	`false`	No

Application

Variable	Description	Default	Required
`ENV_NAME`	Environment label (for example `development`, `staging`, `production`)	`development`	No
`VERSION`	Service version tag	varies	No
`LOG_LEVEL`	Log verbosity: `debug`, `info`, `warn`, or `error`	`debug`	No
`MAX_PAGINATION_LIMIT`	Maximum page size accepted by list endpoints	`100`	No
`MAX_PAGINATION_MONTH_DATE_RANGE`	Maximum month span for date-range queries	`3`	No

Database (PostgreSQL)

The ledger keeps two logical databases — onboarding and transaction — each with a primary and a replica connection block. The variables share one shape; replace {MODULE} with ONBOARDING or TRANSACTION. Replica variables carry a _REPLICA_ infix (for example DB_ONBOARDING_REPLICA_HOST).

Variable	Description	Default	Required
`DB_{MODULE}_HOST`	Primary PostgreSQL host	—	Yes
`DB_{MODULE}_PORT`	PostgreSQL port	—	Yes
`DB_{MODULE}_USER`	Database user	—	Yes
`DB_{MODULE}_PASSWORD`	Database password. Sensitive — do not commit; supply through your secret store.	—	Yes
`DB_{MODULE}_NAME`	Database name	`onboarding` / `transaction`	Yes
`DB_{MODULE}_SSLMODE`	libpq SSL mode: `disable`, `require`, `verify-ca`, or `verify-full`. Use `require` or stronger in production.	`disable`	No
`DB_{MODULE}_MAX_OPEN_CONNS`	Maximum open connections in the pool	`3000`	No
`DB_{MODULE}_MAX_IDLE_CONNS`	Maximum idle connections in the pool	`3000`	No

Document store (MongoDB)

Namespaced per module: MONGO_ONBOARDING_*, MONGO_TRANSACTION_*, and — on the consolidated binary — MONGO_CRM_* and MONGO_FEES_*. All share one shape; replace {NS} with the namespace. They may point at one MongoDB deployment (separate logical databases) or dedicated hosts.

Variable	Description	Default	Required
`MONGO_{NS}_HOST`	MongoDB host	—	Yes
`MONGO_{NS}_PORT`	MongoDB port	—	Yes
`MONGO_{NS}_USER`	Database user	—	Yes
`MONGO_{NS}_PASSWORD`	Database password. Sensitive.	—	Yes
`MONGO_{NS}_NAME`	Database name	namespace name	Yes
`MONGO_{NS}_URI`	Connection scheme: `mongodb` or `mongodb+srv`	`mongodb`	No
`MONGO_{NS}_MAX_POOL_SIZE`	Maximum connection pool size	`1000` (Fees `100`)	No
`MONGO_{NS}_TLS_CA_CERT`	Base64-encoded PEM CA certificate for TLS (for example AWS DocumentDB)	—	No
`MONGO_{NS}_PARAMETERS`	Extra connection-string parameters	—	No

Cache (Redis / Valkey)

Variable	Description	Default	Required
`REDIS_HOST`	Redis/Valkey host and port	—	Yes
`REDIS_PASSWORD`	Authentication password. Sensitive.	—	No
`REDIS_TLS`	Enable TLS for the connection	`false`	No
`REDIS_CA_CERT`	Base64-encoded PEM CA certificate for TLS	—	No
`REDIS_DB`	Logical database index	`0`	No
`REDIS_PROTOCOL`	RESP protocol version	`3`	No
`REDIS_POOL_SIZE`	Connection pool size	`10`	No
`REDIS_MASTER_NAME`	Sentinel master name (Sentinel deployments)	—	No
`REDIS_USE_GCP_IAM`	Authenticate to GCP Memorystore with IAM instead of a password	`false`	No
`REDIS_SERVICE_ACCOUNT`	GCP service account for IAM auth	—	No
`GOOGLE_APPLICATION_CREDENTIALS`	Path to GCP credentials file for IAM auth	—	No

Message broker (RabbitMQ)

Used by the transaction module for balance operations and event fan-out.

Variable	Description	Default	Required
`RABBITMQ_HOST`	Broker host	—	Yes
`RABBITMQ_PORT_AMQP`	AMQP port	—	Yes
`RABBITMQ_PORT_HOST`	Management/HTTP port	—	No
`RABBITMQ_URI`	Connection scheme: `amqp` or `amqps`. Use `amqps` in production.	`amqp`	No
`RABBITMQ_DEFAULT_USER`	Publisher user	—	Yes
`RABBITMQ_DEFAULT_PASS`	Publisher password. Sensitive.	—	Yes
`RABBITMQ_CONSUMER_USER`	Consumer user	—	Yes
`RABBITMQ_CONSUMER_PASS`	Consumer password. Sensitive.	—	Yes
`RABBITMQ_VHOST`	Virtual host	`/`	No
`RABBITMQ_NUMBERS_OF_WORKERS`	Consumer concurrency	`5`	No
`RABBITMQ_PREFETCH`	Consumer prefetch count	`10`	No
`RABBITMQ_TRANSACTION_ASYNC`	Record transactions asynchronously through the broker	`false`	No
`RABBITMQ_TRANSACTION_EVENTS_ENABLED`	Publish transaction events	`false`	No
`RABBITMQ_OVERDRAFT_EVENTS_ENABLED`	Publish overdraft events	`false`	No
`AUDIT_LOG_ENABLED`	Append transactions to an audit log exchange	`false`	No

Throughput

Variable	Description	Default	Required
`BULK_RECORDER_ENABLED`	Batch transaction writes for high-throughput ingestion	`true`	No
`BULK_RECORDER_SIZE`	Batch size trigger (`0` = size-driven off)	`0`	No
`BULK_RECORDER_FLUSH_TIMEOUT_MS`	Flush interval for the batch recorder (milliseconds)	`100`	No
`BULK_RECORDER_MAX_ROWS_PER_INSERT`	Maximum rows per batch insert	`1000`	No

Tracer integration

Optional seam that lets the ledger reserve spending limits against Tracer before committing a transaction. Leave TRACER_BASE_URL unset to disable.

Variable	Description	Default	Required
`TRACER_BASE_URL`	Tracer service URL; setting it enables the reservation client	—	No
`TRACER_TIMEOUT_MS`	Reservation call deadline (milliseconds)	`250`	No
`TRACER_TRANSPORT`	Reservation transport: `grpc` or `rest`	`grpc`	No
`TRACER_TLS_MODE`	Seam security: `mesh` (default, TLS terminated by the service mesh) or `mtls`	`mesh`	No
`TRACER_TLS_CERT_FILE`	Client certificate PEM path (when `mtls`)	—	If `mtls`
`TRACER_TLS_KEY_FILE`	Client private-key PEM path (when `mtls`). Sensitive.	—	If `mtls`
`TRACER_TLS_CA_FILE`	CA certificate PEM path (when `mtls`)	—	If `mtls`

With TRACER_BASE_URL set, the seam uses the default grpc transport unless you set TRACER_TRANSPORT=rest. The gRPC transport requires the Tracer service to expose its reservation gRPC seam — set TRACER_GRPC_PORT on Tracer (see Tracer environment variables). Under TRACER_TLS_MODE=mtls, the client certificate, key, and CA paths above are required.

CRM and Fees

These variables apply to the standalone CRM service today, and to the ledger process once CRM and Fees fold into it. They protect account-holder PII and configure the field-encryption backend.

Variable	Description	Default	Required
`LCRYPTO_HASH_SECRET_KEY`	64-hex hashing key for holder PII. Sensitive — generate a unique value per environment.	—	Yes (CRM)
`LCRYPTO_ENCRYPT_SECRET_KEY`	64-hex encryption key for holder PII. Sensitive.	—	Yes (CRM)
`KMS_VENDOR`	Field-encryption backend: `none` or `hashicorp-vault`	`none`	No
`KMS_VAULT_ADDR`	Vault address (when `hashicorp-vault`)	—	No
`KMS_VAULT_AUTH_METHOD`	Vault auth method: `token` or `approle`. Use `approle` in `byoc`/`saas`.	`token`	No
`KMS_VAULT_ROLE_ID`	Vault AppRole role ID (when `approle`)	—	No
`KMS_VAULT_SECRET_ID`	Vault AppRole secret ID (when `approle`). Sensitive.	—	No
`DEFAULT_CURRENCY`	Fallback fee currency (ISO 4217)	`USD`	No

Shared configuration backbone

The following blocks are identical across Lerian products and are documented in full in the BYOC configuration reference. They default off; a single-tenant BYOC deployment can ignore all of the optional ones.

Access Manager authentication — PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_HOST. Enable in production.
Multi-tenancy — MULTI_TENANT_*. Off by default; enables per-tenant database resolution.
Service discovery — SD_* (Consul). Off by default.
Event streaming — STREAMING_* (lib-streaming producer). Off by default on the ledger.
OpenTelemetry — ENABLE_TELEMETRY, OTEL_*. Telemetry is OTLP push.

​Ports and health endpoints

​Deployment and TLS

​Application

​Database (PostgreSQL)

​Document store (MongoDB)

​Cache (Redis / Valkey)

​Message broker (RabbitMQ)

​Throughput

​Tracer integration

​CRM and Fees

​Shared configuration backbone

Ports and health endpoints

Deployment and TLS

Application

Database (PostgreSQL)

Document store (MongoDB)

Cache (Redis / Valkey)

Message broker (RabbitMQ)

Throughput

Tracer integration

CRM and Fees

Shared configuration backbone