> ## 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.
# Variables de entorno
> Consulta la referencia de variables de entorno usadas para configurar el servicio de ledger Midaz, organizadas por categoría y con valores por defecto.
Esta referencia enumera las variables de entorno que configuran el **servicio de ledger Midaz**. Midaz es el motor de partida doble source-available (ELv2). Sirve las API de onboarding y de transacción en un único puerto. Defines estas variables en el momento del despliegue, mediante valores de Helm, Docker Compose o el entorno de tu orquestador. Una variable requerida que no definas hace que el servidor falle al arrancar.
Cada producto de Lerian comparte un conjunto de bloques de configuración: postura de TLS, OpenTelemetry, autenticación de Access Manager, multi-tenancy, descubrimiento de servicios y streaming de eventos. La [referencia de configuración BYOC](/es/reference/byoc-configuration) documenta estos bloques. Esta página se centra en lo que es distintivo del ledger.
La consolidación ya está lista. Despliegas el servicio **ledger** (rutas unificadas de onboarding + transacción), y **CRM** y **Fees** están compilados dentro de ese mismo proceso del ledger — el binario del ledger lee las variables de CRM y Fees que aparecen abajo. Tracer vive en el mismo repositorio y se despliega como su propio servicio opcional. Los antiguos componentes `onboarding`, `transaction` y `mdz` ya no existen como desplegables separados. El chart de Helm aún incluye un despliegue `crm` independiente heredado, desactivado por defecto.
## Puertos y endpoints de salud
El ledger ejecuta un único proceso HTTP. Consulta la [referencia de salud y readiness](/es/reference/health-and-readiness) para el contrato de las sondas.
| Superficie | Variable de puerto | Valor por defecto | Endpoints |
| -------------------------------------------------------------------------------------------- | -------------------------------- | ----------------- | -------------------------------- |
| HTTP del ledger (onboarding + transacción) | `SERVER_PORT` / `SERVER_ADDRESS` | `3002` | `/health`, `/readyz`, `/version` |
| HTTP de CRM (despliegue independiente heredado, desactivado por defecto en el chart de Helm) | `SERVER_PORT` / `SERVER_ADDRESS` | `4003` | `/health`, `/readyz` |
El ledger usa push OTLP para la telemetría y no expone un endpoint `/metrics` de scraping.
## Despliegue y TLS
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `DEPLOYMENT_MODE` | Sabor de despliegue: `local`, `byoc` o `saas`. En `saas`, el TLS es obligatorio para cada conexión a una dependencia y el servidor se niega a arrancar sin él. En `byoc`, el TLS se recomienda y se advierte en lugar de imponerse. También etiqueta la respuesta de `/readyz`. | `local` | No |
| `ALLOW_INSECURE_TLS` | Omite la imposición de TLS por conexión en los DSN de infraestructura. Déjala sin definir o en `false` en producción; ponla en `true` solo para infraestructura local en texto plano. | `false` | No |
## Aplicación
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `ENV_NAME` | Etiqueta del entorno (por ejemplo `development`, `staging`, `production`) | `development` | No |
| `VERSION` | Etiqueta de versión del servicio | varía | No |
| `LOG_LEVEL` | Verbosidad de los logs: `debug`, `info`, `warn` o `error` | `debug` | No |
| `MAX_PAGINATION_LIMIT` | Tamaño máximo de página aceptado por los endpoints de listado | `100` | No |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Máximo de meses para consultas por rango de fechas. La configuración de ejemplo incluida define `3`. | `1` | No |
## Base de datos (PostgreSQL)
El ledger mantiene dos bases de datos lógicas —`onboarding` y `transaction`— cada una con un bloque de conexión primaria y otro de réplica. Las variables comparten una misma forma. Sustituye `{MODULE}` por `ONBOARDING` o `TRANSACTION`. Las variables de réplica llevan un infijo `_REPLICA_` (por ejemplo `DB_ONBOARDING_REPLICA_HOST`).
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------- |
| `DB_{MODULE}_HOST` | Host primario de PostgreSQL | — | Sí |
| `DB_{MODULE}_PORT` | Puerto de PostgreSQL | — | Sí |
| `DB_{MODULE}_USER` | Usuario de la base de datos | — | Sí |
| `DB_{MODULE}_PASSWORD` | Contraseña de la base de datos. Sensible: no la incluyas en el control de versiones; proporciónala a través de tu almacén de secretos. | — | Sí |
| `DB_{MODULE}_NAME` | Nombre de la base de datos | `onboarding` / `transaction` | Sí |
| `DB_{MODULE}_SSLMODE` | Modo SSL de libpq: `disable`, `require`, `verify-ca` o `verify-full`. Usa `require` o más estricto en producción. | `disable` | No |
| `DB_{MODULE}_MAX_OPEN_CONNS` | Máximo de conexiones abiertas en el pool | `3000` | No |
| `DB_{MODULE}_MAX_IDLE_CONNS` | Máximo de conexiones inactivas en el pool | `3000` | No |
## Almacén de documentos (MongoDB)
Las variables de MongoDB usan un espacio de nombres por módulo: `MONGO_ONBOARDING_*`, `MONGO_TRANSACTION_*` y —en el binario consolidado— `MONGO_CRM_*` y `MONGO_FEES_*`. Todas comparten una misma forma. Sustituye `{NS}` por el espacio de nombres. Pueden apuntar a un único despliegue de MongoDB (bases de datos lógicas separadas) o a hosts dedicados.
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------- | ----------------------------------------------------------------------------- | ----------------------------- | --------- |
| `MONGO_{NS}_HOST` | Host de MongoDB | — | Sí |
| `MONGO_{NS}_PORT` | Puerto de MongoDB | — | Sí |
| `MONGO_{NS}_USER` | Usuario de la base de datos | — | Sí |
| `MONGO_{NS}_PASSWORD` | Contraseña de la base de datos. Sensible. | — | Sí |
| `MONGO_{NS}_NAME` | Nombre de la base de datos | nombre del espacio de nombres | Sí |
| `MONGO_{NS}_URI` | Esquema de conexión: `mongodb` o `mongodb+srv` | `mongodb` | No |
| `MONGO_{NS}_MAX_POOL_SIZE` | Tamaño máximo del pool de conexiones | `1000` (Fees `100`) | No |
| `MONGO_{NS}_TLS_CA_CERT` | Certificado CA PEM codificado en base64 para TLS (por ejemplo AWS DocumentDB) | — | No |
| `MONGO_{NS}_PARAMETERS` | Parámetros adicionales de la cadena de conexión | — | No |
## Caché (Redis / Valkey)
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------- | ----------------------------------------------------------------- | ----------------- | --------- |
| `REDIS_HOST` | Host y puerto de Redis/Valkey | — | Sí |
| `REDIS_PASSWORD` | Contraseña de autenticación. Sensible. | — | No |
| `REDIS_TLS` | Habilita TLS para la conexión | `false` | No |
| `REDIS_CA_CERT` | Certificado CA PEM codificado en base64 para TLS | — | No |
| `REDIS_DB` | Índice de la base de datos lógica | `0` | No |
| `REDIS_PROTOCOL` | Versión del protocolo RESP | `3` | No |
| `REDIS_POOL_SIZE` | Tamaño del pool de conexiones | `10` | No |
| `REDIS_MASTER_NAME` | Nombre del master de Sentinel (despliegues Sentinel) | — | No |
| `REDIS_USE_GCP_IAM` | Autentícate en GCP Memorystore con IAM en lugar de una contraseña | `false` | No |
| `REDIS_SERVICE_ACCOUNT` | Cuenta de servicio de GCP para la autenticación IAM | — | No |
| `GOOGLE_APPLICATION_CREDENTIALS` | Ruta al archivo de credenciales de GCP para la autenticación IAM | — | No |
## Broker de mensajes (RabbitMQ)
El módulo de transacción usa RabbitMQ para operaciones de saldo y difusión de eventos.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `RABBITMQ_HOST` | Host del broker | — | Sí |
| `RABBITMQ_PORT_HOST` | **Puerto AMQP** con el que se conecta al broker. A pesar del nombre, este es el puerto que usa la cadena de conexión (`3003` en la infraestructura incluida). | — | Sí |
| `RABBITMQ_PORT_AMQP` | **Puerto de gestión/HTTP** informado en la conexión del health check (`3004` en la infraestructura incluida). A pesar del nombre, no se usa para conectarse por AMQP. | — | No |
| `RABBITMQ_URI` | Esquema de conexión: `amqp` o `amqps`. Usa `amqps` en producción. | `amqp` | No |
| `RABBITMQ_DEFAULT_USER` | Usuario publicador | — | Sí |
| `RABBITMQ_DEFAULT_PASS` | Contraseña del publicador. Sensible. | — | Sí |
| `RABBITMQ_CONSUMER_USER` | Usuario consumidor | — | Sí |
| `RABBITMQ_CONSUMER_PASS` | Contraseña del consumidor. Sensible. | — | Sí |
| `RABBITMQ_VHOST` | Host virtual | `/` | No |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Concurrencia de consumidores | `5` | No |
| `RABBITMQ_NUMBERS_OF_PREFETCH` | Recuento de prefetch del consumidor | `10` | No |
| `RABBITMQ_TRANSACTION_ASYNC` | Registra transacciones de forma asíncrona a través del broker | `false` | No |
| `RABBITMQ_TRANSACTION_EVENTS_ENABLED` | Publica eventos de transacción. Cualquier valor distinto de `false` —incluido no definirla— habilita la publicación; define `false` de forma explícita para deshabilitarla. La configuración de ejemplo incluida define `false`. | habilitado | No |
| `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` | Publica eventos de sobregiro. Cualquier valor distinto de `false` —incluido no definirla— habilita la publicación; define `false` de forma explícita para deshabilitarla. La configuración de ejemplo incluida define `false`. | habilitado | No |
| `AUDIT_LOG_ENABLED` | Añade transacciones a un exchange de log de auditoría. Cualquier valor distinto de `false` —incluido no definirla— lo habilita; define `false` de forma explícita para deshabilitarlo. La configuración de ejemplo incluida define `false`. | habilitado | No |
## Rendimiento
| Variable | Descripción | Valor por defecto | Requerida |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | --------- |
| `BULK_RECORDER_ENABLED` | Agrupa en lote las escrituras de transacciones para ingesta de alto throughput | `true` | No |
| `BULK_RECORDER_SIZE` | Umbral de tamaño de lote. Si no la defines, Midaz la deriva de `RABBITMQ_NUMBERS_OF_WORKERS` × `RABBITMQ_NUMBERS_OF_PREFETCH` (50 con los valores por defecto de workers y prefetch). | workers × prefetch | No |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS` | Intervalo de vaciado del registrador por lotes (milisegundos) | `100` | No |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Máximo de filas por inserción en lote | `1000` | No |
## Integración con Tracer
La costura opcional permite al ledger reservar límites de gasto contra Tracer antes de que confirme una transacción. Deja `TRACER_BASE_URL` sin definir para deshabilitarla.
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------- | ----------------------------------------------------------------------------------------- | ----------------- | --------- |
| `TRACER_BASE_URL` | URL del servicio Tracer; definirla habilita el cliente de reserva | — | No |
| `TRACER_TIMEOUT_MS` | Plazo de la llamada de reserva (milisegundos) | `250` | No |
| `TRACER_TRANSPORT` | Transporte de reserva: `grpc` o `rest` | `grpc` | No |
| `TRACER_TLS_MODE` | Seguridad de la costura: `mesh` (por defecto, TLS terminado por el service mesh) o `mtls` | `mesh` | No |
| `TRACER_TLS_CERT_FILE` | Ruta del certificado PEM del cliente (cuando `mtls`) | — | Si `mtls` |
| `TRACER_TLS_KEY_FILE` | Ruta de la clave privada PEM del cliente (cuando `mtls`). Sensible. | — | Si `mtls` |
| `TRACER_TLS_CA_FILE` | Ruta del certificado CA PEM (cuando `mtls`) | — | Si `mtls` |
Con `TRACER_BASE_URL` definida, la costura usa el transporte `grpc` por defecto a menos que definas `TRACER_TRANSPORT=rest`. El transporte gRPC exige que el servicio Tracer exponga su costura gRPC de reserva: define `TRACER_GRPC_PORT` en Tracer (consulta [Variables de entorno de Tracer](/es/tracer/tracer-environment-variables)). Con `TRACER_TLS_MODE=mtls`, debes definir las rutas del certificado de cliente, la clave y la CA de arriba.
## CRM y Fees
El proceso del ledger lee estas variables — CRM y Fees están compilados dentro del binario del ledger. Protegen la PII de los titulares de cuenta y configuran el backend de cifrado de campos.
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------------- | ------------------------------------------------------------------------------------------------ | ----------------- | --------- |
| `LCRYPTO_HASH_SECRET_KEY` | Clave de hashing de 64 hex para la PII del titular. Sensible: genera un valor único por entorno. | — | Sí (CRM) |
| `LCRYPTO_ENCRYPT_SECRET_KEY` | Clave de cifrado de 64 hex para la PII del titular. Sensible. | — | Sí (CRM) |
| `KMS_VENDOR` | Backend de cifrado de campos: `none` o `hashicorp-vault` | `none` | No |
| `KMS_VAULT_ADDR` | Dirección de Vault (cuando `hashicorp-vault`) | — | No |
| `KMS_VAULT_AUTH_METHOD` | Método de autenticación de Vault: `token` o `approle`. Usa `approle` en `byoc`/`saas`. | `token` | No |
| `KMS_VAULT_ROLE_ID` | ID de rol de AppRole de Vault (cuando `approle`) | — | No |
| `KMS_VAULT_SECRET_ID` | ID de secreto de AppRole de Vault (cuando `approle`). Sensible. | — | No |
| `DEFAULT_CURRENCY` | Moneda de tarifa de respaldo (ISO 4217) | `USD` | No |
## Base de configuración compartida
Los siguientes bloques son idénticos en todos los productos de Lerian. La [referencia de configuración BYOC](/es/reference/byoc-configuration) los documenta por completo. Están desactivados por defecto. Un despliegue BYOC single-tenant puede ignorar todos los opcionales.
* **Autenticación de Access Manager** — `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_HOST`. Habilítala en producción.
* **Multi-tenancy** — `MULTI_TENANT_*`. Desactivado por defecto. Habilita la resolución de base de datos por tenant.
* **Descubrimiento de servicios** — `SD_*` (Consul). Desactivado por defecto.
* **Streaming de eventos** — `STREAMING_*` (productor de lib-streaming). Desactivado por defecto en el ledger.
* **OpenTelemetry** — `ENABLE_TELEMETRY`, `OTEL_*`. La telemetría es push OTLP.