Variables de entorno

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 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 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). 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 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.

​Puertos y endpoints de salud

​Despliegue y TLS

​Aplicación

​Base de datos (PostgreSQL)

​Almacén de documentos (MongoDB)

​Caché (Redis / Valkey)

​Broker de mensajes (RabbitMQ)

​Rendimiento

​Integración con Tracer

​CRM y Fees

​Columna vertebral de configuración compartida

Puertos y endpoints de salud

Despliegue y TLS

Aplicación

Base de datos (PostgreSQL)

Almacén de documentos (MongoDB)

Caché (Redis / Valkey)

Broker de mensajes (RabbitMQ)

Rendimiento

Integración con Tracer

CRM y Fees

Columna vertebral de configuración compartida