Variables de entorno

Esta referencia enumera las variables de entorno que configuran el servicio ledger de Midaz. Midaz es el motor de partida doble. 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. Un valor que el servidor no puede leer también hace que falle al iniciar, y el error nombra la variable. Un booleano acepta solo true o false. Un número debe ser entero. Una duración necesita una unidad, como 12s. Cada producto de Lerian comparte un conjunto de bloques de configuración: postura de TLS, OpenTelemetry, autenticación de Access Manager, 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.

Despliegas el servicio ledger. Atiende las rutas de onboarding y transacciones, y CRM y Fees se ejecutan en el mismo proceso. El ledger lee las variables de CRM y Fees que se muestran abajo. Tracer se distribuye como su propio servicio opcional. El chart de Helm también 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_ADDRESS`	`:3002`	`/health`, `/readyz`, `/version`

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. En `saas`, el servidor también se niega a iniciar cuando `PLUGIN_AUTH_ENABLED` no es `true`. 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
`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`	Ventana predeterminada en meses para las listas de transacciones y operaciones cuando no se proporciona ni la fecha inicial ni la final.	`1`	No
`TRANSACTION_BATCH_MAX_SIZE`	Número máximo de transacciones en una solicitud de lote atómico. Acepta de `1` a `50`. Cualquier otro valor detiene el servidor al iniciar.	`10`	No
`OPENAPI_DOCS_ENABLED`	Sirve la spec OpenAPI 3.1 en `/openapi.json` y `/openapi.yaml`, y la documentación interactiva en `/docs`	`false`	No
`SHUTDOWN_DRAIN_DELAY`	Espera entre marcar `/readyz` como no disponible al apagar y cerrar el servidor HTTP, como duración de Go (por ejemplo `12s`). `0` omite la espera. Un valor mayor que `20s` usa `20s`.	`12s`	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. Sin valor o `0` usa el valor predeterminado.	`25`	No
`DB_{MODULE}_MAX_IDLE_CONNS`	Máximo de conexiones inactivas en el pool. Sin valor o `0` usa el valor predeterminado.	`10`	No
`DB_TRANSACTION_ROUTE_TX_READS_TO_PRIMARY`	Envía las lecturas del flujo de transacciones al primario, no a la réplica. `false` lo desactiva.	`true`	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	`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`	Credenciales de la cuenta de servicio de GCP codificadas en Base64 para la autenticación IAM	—	Cuando `REDIS_USE_GCP_IAM=true`

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_OPERATION_TIMEOUT`	Espera máxima a que el broker confirme una publicación, como duración de Go (por ejemplo `5s`).	`5s`	No
`RABBITMQ_HEALTH_CHECK_URL`	URL de administración de RabbitMQ que verifica `/readyz`. La verificación usa las credenciales de `RABBITMQ_DEFAULT_USER`, por lo que ese usuario necesita acceso a la API de administración. Un valor vacío omite la verificación. El chart de Helm reemplaza un valor vacío por la URL de administración de RabbitMQ.	—	No
`RABBITMQ_OVERDRAFT_EVENTS_ENABLED`	Publica los eventos de sobregiro en RabbitMQ y en streaming. `false` desactiva los dos. Consulta Sobregiro de saldo.	`true`	No
`AUDIT_LOG_ENABLED`	Publica mensajes de auditoría de transacciones en RabbitMQ. Consulta Auditabilidad.	`false`	No

Rendimiento

Variable	Descripción	Predeterminado	Obligatorio
`BULK_RECORDER_ENABLED`	Agrupa las escrituras de transacciones en lotes para una ingesta de alto rendimiento. Solo tiene efecto cuando `RABBITMQ_TRANSACTION_ASYNC=true`.	`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 verifique una transacción con Tracer antes de confirmarla. Deja TRACER_BASE_URL sin configurar para desactivarlo.

Variable	Descripción	Predeterminado	Obligatorio
`TRACER_BASE_URL`	Dirección del seam gRPC de Tracer, `host:4021` (el `TRACER_GRPC_PORT` de Tracer). Configurarla habilita el cliente de reserva.	—	No
`TRACER_TIMEOUT_MS`	Plazo límite de la llamada de reserva (milisegundos)	`250`	No
`TRACER_TLS_MODE`	Seguridad del seam: `mesh` (predeterminado, TLS terminado por el service mesh), `mtls` o `server`	`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` o `server`)	—	Si `mtls` o `server`
`TRACER_M2M_CLIENT_ID`	Se lee con `PLUGIN_AUTH_ENABLED=true`.	—	Obligatoria cuando `TRACER_BASE_URL` está configurada y `PLUGIN_AUTH_ENABLED=true`.
`TRACER_M2M_CLIENT_SECRET`	Se lee con `PLUGIN_AUTH_ENABLED=true`. Sensible.	—	Obligatoria cuando `TRACER_BASE_URL` está configurada y `PLUGIN_AUTH_ENABLED=true`.
`TRACER_M2M_WAIT_TIMEOUT_MS`	Se lee solo con `PLUGIN_AUTH_ENABLED=true`. Acepta de `1` a `5000` (milisegundos).	`3000`	No
`TRACER_API_KEY`	Se lee con `PLUGIN_AUTH_ENABLED=false`. Cuando `TRACER_BASE_URL` está configurada, el ledger no arranca si también configuras `PLUGIN_AUTH_ENABLED=true`. Tracer la acepta solo con `API_KEY_ENABLED=true` y `PLUGIN_AUTH_ENABLED=false`. Sensible.	—	No

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 `KMS_VENDOR=hashicorp-vault`
`KMS_VAULT_AUTH_METHOD`	Método de autenticación de Vault: `token` o `approle`. Usa `token` solo en `local`; usa `approle` en `byoc`/`saas`.	—	Cuando `KMS_VENDOR=hashicorp-vault`
`KMS_VAULT_ROLE_ID`	ID de rol de AppRole de Vault	—	Cuando `KMS_VAULT_AUTH_METHOD=approle`
`KMS_VAULT_SECRET_ID`	ID de secreto de AppRole de Vault. Sensible.	—	Cuando `KMS_VAULT_AUTH_METHOD=approle`

Configuración compartida entre los productos de Lerian

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 puede ignorar todos los opcionales.

Autenticación de Access Manager: PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_HOST. Habilítala en producción.
Descubrimiento de servicios: SD_* (Consul). Desactivado de forma predeterminada.
Streaming de eventos: 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

​Configuración compartida entre los productos de Lerian

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

Configuración compartida entre los productos de Lerian