> ## 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 del servicio ledger de Midaz: puertos, TLS, modo de despliegue y la configuración de CRM o Fees para las API de onboarding y transacciones.
Esta referencia enumera las variables de entorno que configuran el **servicio ledger de Midaz**. Midaz es el motor de partida doble source-available (ELv2). Sirve las API de onboarding y transacciones en un solo puerto. Configuras estas variables en el momento del despliegue, mediante valores de Helm, Docker Compose o el entorno de tu orquestador. Una variable obligatoria que no configures hace que el servidor falle al iniciar.
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 de BYOC](/es/reference/byoc-configuration) documenta estos bloques. Esta página se centra en lo distintivo del ledger.
La consolidación ya se aplicó. Despliegas el servicio **ledger** (rutas unificadas de onboarding y transacciones), y **CRM** y **Fees** se compilan dentro de ese mismo proceso ledger. El binario del ledger lee las variables de CRM y Fees que se muestran abajo. Tracer vive en el mismo repositorio y se distribuye como su propio servicio opcional. Los antiguos componentes `onboarding`, `transaction` y `mdz` ya no existen como unidades de despliegue independientes. El chart de Helm todavía incluye un despliegue heredado independiente de `crm`, desactivado de forma predeterminada.
## Puertos y endpoints de salud
El ledger ejecuta un solo proceso HTTP. Consulta la [referencia de salud y disponibilidad](/es/reference/health-and-readiness) para conocer el contrato de las sondas.
| Superficie | Variable de puerto | Predeterminado | Endpoints |
| - | - | - | - |
| HTTP del ledger (onboarding + transacciones) | `SERVER_PORT` / `SERVER_ADDRESS` | `3002` | `/health`, `/readyz`, `/version` |
| HTTP de CRM (despliegue heredado independiente, desactivado de forma predeterminada en el chart de Helm) | `SERVER_PORT` / `SERVER_ADDRESS` | `4003` | `/health`, `/readyz` |
El ledger usa OTLP push para la telemetría y no expone un endpoint de scrape `/metrics`.
## Despliegue y TLS
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Modo de despliegue: `local`, `byoc` o `saas`. En `saas`, TLS es obligatorio para toda conexión con una dependencia y el servidor se niega a iniciar sin él. En `byoc`, TLS se recomienda y genera una advertencia en vez de exigirse. También etiqueta la respuesta de `/readyz`. | `local` | No |
| `ALLOW_INSECURE_TLS` | Omite la aplicación de TLS por conexión en los DSN de infraestructura. Déjala sin configurar o en `false` en producción; configúrala en `true` solo para infraestructura local en texto plano. | `false` | No |
## Aplicación
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `ENV_NAME` | Etiqueta de entorno (por ejemplo, `development`, `staging`, `production`) | `development` | No |
| `VERSION` | Etiqueta de versión del servicio | varía | No |
| `LOG_LEVEL` | Nivel de detalle del log: `debug`, `info`, `warn` o `error` | `debug` | No |
| `MAX_PAGINATION_LIMIT` | Tamaño máximo de página aceptado por los endpoints de lista | `100` | No |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Intervalo máximo de meses para las consultas de rango de fechas. La configuración de ejemplo incluida trae `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 primario y uno de réplica. Las variables comparten una misma forma. Reemplaza `{MODULE}` por `ONBOARDING` o `TRANSACTION`. Las variables de réplica llevan el infijo `_REPLICA_` (por ejemplo, `DB_ONBOARDING_REPLICA_HOST`).
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `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 subas en un commit; provéela mediante 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 un modo 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 namespace por módulo: `MONGO_ONBOARDING_*`, `MONGO_TRANSACTION_*` y, en el binario consolidado, `MONGO_CRM_*` y `MONGO_FEES_*`. Todas comparten una misma forma. Reemplaza `{NS}` por el namespace. Pueden apuntar a un solo despliegue de MongoDB (con bases de datos lógicas separadas) o a hosts dedicados.
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `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 namespace | 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 | Predeterminado | Obligatorio |
| - | - | - | - |
| `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 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 con Sentinel) | — | No |
| `REDIS_USE_GCP_IAM` | Autentica ante 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 pipeline interno asíncrono de operaciones de saldo usa RabbitMQ cuando `RABBITMQ_TRANSACTION_ASYNC=true`. RabbitMQ también transporta ciertos exchanges salientes heredados.
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `RABBITMQ_HOST` | Host del broker | — | Sí |
| `RABBITMQ_PORT_HOST` | **Puerto AMQP** usado para conectar con el broker. A pesar del nombre, es el puerto que usa la cadena de conexión (`3003` en la infraestructura incluida). | — | Sí |
| `RABBITMQ_PORT_AMQP` | **Puerto de administración/HTTP** que se reporta en la conexión de verificación de estado (`3004` en la infraestructura incluida). A pesar del nombre, no se usa para conectar por AMQP. | — | No |
| `RABBITMQ_URI` | Esquema de conexión: `amqp` o `amqps`. Usa `amqps` en producción. | `amqp` | No |
| `RABBITMQ_DEFAULT_USER` | Usuario del publicador | — | Sí |
| `RABBITMQ_DEFAULT_PASS` | Contraseña del publicador. Sensible. | — | Sí |
| `RABBITMQ_CONSUMER_USER` | Usuario del consumidor | — | Sí |
| `RABBITMQ_CONSUMER_PASS` | Contraseña del consumidor. Sensible. | — | Sí |
| `RABBITMQ_VHOST` | Host virtual | `/` | No |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Concurrencia del consumidor | `5` | No |
| `RABBITMQ_NUMBERS_OF_PREFETCH` | Cantidad de prefetch del consumidor | `10` | No |
| `RABBITMQ_TRANSACTION_ASYNC` | Registra las transacciones de forma asíncrona a través del broker | `false` | No |
| `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` | Publica eventos de sobregiro. Cualquier valor distinto de `false` (incluido sin configurar) habilita la publicación; configura `false` explícitamente para desactivarla. La configuración de ejemplo incluida trae `false`. | habilitado | No |
| `AUDIT_LOG_ENABLED` | Agrega las transacciones a un exchange de log de auditoría. Cualquier valor distinto de `false` (incluido sin configurar) lo habilita; configura `false` explícitamente para desactivarlo. La configuración de ejemplo incluida trae `false`. | habilitado | No |
## Rendimiento
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `BULK_RECORDER_ENABLED` | Agrupa las escrituras de transacciones en lotes para una ingesta de alto rendimiento | `true` | No |
| `BULK_RECORDER_SIZE` | Umbral de tamaño del lote. Si no se configura, Midaz lo calcula a partir de `RABBITMQ_NUMBERS_OF_WORKERS` × `RABBITMQ_NUMBERS_OF_PREFETCH` (50 con los valores predeterminados de worker y prefetch). | workers × prefetch | No |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS` | Intervalo de flush del registrador de 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
El seam opcional permite que el ledger reserve límites de gasto contra Tracer antes de confirmar una transacción. Deja `TRACER_BASE_URL` sin configurar para desactivarlo.
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `TRACER_BASE_URL` | URL del servicio Tracer; configurarla habilita el cliente de reserva | — | No |
| `TRACER_TIMEOUT_MS` | Plazo límite de la llamada de reserva (milisegundos) | `250` | No |
| `TRACER_TRANSPORT` | Transporte de la reserva: `grpc` o `rest` | `grpc` | No |
| `TRACER_TLS_MODE` | Seguridad del seam: `mesh` (predeterminado, 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` configurada, el seam usa el transporte `grpc` predeterminado a menos que configures `TRACER_TRANSPORT=rest`. El transporte gRPC requiere que el servicio Tracer exponga su seam gRPC de reservas. Configura `TRACER_GRPC_PORT` en Tracer (consulta [Variables de entorno de Tracer](/es/products/tracer/tracer-environment-variables)). Bajo `TRACER_TLS_MODE=mtls`, debes configurar las rutas del certificado de cliente, la clave y la CA indicadas arriba.
## CRM y Fees
El proceso del ledger lee estas variables porque CRM y Fees se compilan dentro del binario del ledger. Protegen la PII del titular de la cuenta y configuran el backend de cifrado de campos.
| Variable | Descripción | Predeterminado | Obligatorio |
| - | - | - | - |
| `LCRYPTO_HASH_SECRET_KEY` | Clave de hashing de 64 caracteres hexadecimales para la PII del titular. Sensible: genera un valor único por entorno. | — | Sí (CRM) |
| `LCRYPTO_ENCRYPT_SECRET_KEY` | Clave de cifrado de 64 caracteres hexadecimales 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 |
## Columna vertebral de configuración compartida
Los siguientes bloques son idénticos en todos los productos de Lerian. La [referencia de configuración de BYOC](/es/reference/byoc-configuration) los documenta en detalle. Están desactivados de forma predeterminada. Un despliegue BYOC de un solo 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 de forma predeterminada. Habilita la resolución de bases de datos por tenant.
* **Descubrimiento de servicios**: `SD_*` (Consul). Desactivado de forma predeterminada.
* **Streaming de eventos**: `STREAMING_*` (productor de lib-streaming). Desactivado de forma predeterminada en el ledger.
* **OpenTelemetry**: `ENABLE_TELEMETRY`, `OTEL_*`. La telemetría es OTLP push.