> ## 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
> Referencia de las variables de entorno usadas para configurar el servicio de ledger Midaz, organizadas por categoría.
Esta referencia enumera las variables de entorno usadas para configurar el **servicio de ledger Midaz** —el motor de partida doble source-available (ELv2) que sirve las API de onboarding y de transacción en un único puerto—. Las defines en el momento del despliegue, mediante valores de Helm, Docker Compose o el entorno de tu orquestador. Las variables marcadas como requeridas hacen que el servidor falle al arrancar si no se definen.
Para los bloques de configuración que comparte cada producto de Lerian —postura de TLS, OpenTelemetry, autenticación de Access Manager, multi-tenancy, descubrimiento de servicios y streaming de eventos— consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration). Esta página se centra en lo que es distintivo del ledger.
Midaz está en plena consolidación. Lo que despliegas hoy es el servicio **ledger** (rutas unificadas de onboarding + transacción) más un servicio **CRM** independiente. La disposición consolidada de binario único —que integra CRM y Fees en el proceso del ledger y traslada Tracer al mismo repositorio— se está desplegando de forma gradual. Las variables de CRM y Fees siguientes aplican hoy al servicio CRM independiente, y al proceso del ledger una vez que la consolidación llegue a tu entorno. Los antiguos componentes `onboarding`, `transaction` y `mdz` ya no existen como desplegables separados.
## 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 (servicio independiente, disposición actual entregada) | `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 | `3` | 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)
Con espacios 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)
Usado por el módulo de transacción para operaciones de saldo y difusión de eventos.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------------- | ----------------------------------------------------------------- | ----------------- | --------- |
| `RABBITMQ_HOST` | Host del broker | — | Sí |
| `RABBITMQ_PORT_AMQP` | Puerto AMQP | — | Sí |
| `RABBITMQ_PORT_HOST` | Puerto de gestión/HTTP | — | 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_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 | `false` | No |
| `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` | Publica eventos de sobregiro | `false` | No |
| `AUDIT_LOG_ENABLED` | Añade transacciones a un exchange de log de auditoría | `false` | 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 (`0` = disparo por tamaño desactivado) | `0` | 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
Costura opcional que permite al ledger reservar límites de gasto contra Tracer antes de confirmar 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`, las rutas del certificado de cliente, la clave y la CA de arriba son obligatorias.
## CRM y Fees
Estas variables aplican hoy al servicio CRM independiente, y al proceso del ledger una vez que CRM y Fees se integren en él. 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 y están documentados por completo en la [referencia de configuración BYOC](/es/reference/byoc-configuration). 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.