> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Reference for the environment variables used to configure the Midaz ledger service, organized by category.

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](/en/reference/byoc-configuration). This page focuses on what is distinctive to the ledger.

<Note>
  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.
</Note>

## Ports and health endpoints

The ledger runs one HTTP process. See the [health and readiness reference](/en/reference/health-and-readiness) 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` |

<Note>
  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](/en/tracer/tracer-environment-variables)). Under `TRACER_TLS_MODE=mtls`, the client certificate, key, and CA paths above are required.
</Note>

## 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](/en/reference/byoc-configuration). 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.