Variables de entorno

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

​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

​Base 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

Base de configuración compartida