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