> ## 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
> Variables de entorno en tiempo de despliegue para Lerian SPB: runtime, conectividad STR/RSFN, firma de mensajes y certificados, persistencia, eventos y seguridad.
Lerian SPB es la integración de mensajería nativa de Lerian para el STR (Sistema de Transferência de Reservas), el sistema de liquidación bruta en tiempo real de BACEN, al que se llega a través de la RSFN. Configura estas variables en el momento del despliegue. Un cambio surte efecto solo después de reiniciar el servicio. La mayoría de las variables son específicas de este riel. Para los parámetros que se comportan igual en todos los servicios Go de Lerian (postura de despliegue, almacenes de datos, multi-tenancy y telemetría), consulta [Fundamentos de configuración de BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, **Obligatorio** marca una variable que debes configurar, de forma global o bajo la condición indicada. Un calificador como *En production* o *Si está habilitado* acota cuándo se aplica el requisito. `—` significa que no hay un valor predeterminado.
`ENV_NAME` activa las barreras de seguridad más estrictas. Configúralo como `production` o `staging` y el servicio exige TLS en Redis, RabbitMQ y la conexión STR. También requiere un backend de custodia de firma respaldado por hardware y rechaza las superficies exclusivas de desarrollo. `ENV_NAME` no tiene un valor predeterminado. Configúralo explícitamente. El servicio se niega a empezar cuando `ENV_NAME` no está configurado o contiene un valor no reconocido.
## Runtime y servidor
| Variable | Descripción | Predeterminado | Obligatorio |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | ----------- |
| `ENV_NAME` | Entorno de runtime. Debe ser uno de `production`, `staging` o `develop`. Production y staging activan las barreras de seguridad descritas antes. | — | Sí |
| `SERVICE_NAME` | Identificador del servicio usado en logs y telemetría. | Predeterminado del servicio | No |
| `LOG_LEVEL` | Nivel de detalle del log (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_PORT` | Puerto de escucha HTTP. Las superficies de liveness, readiness y systemplane se vinculan a este mismo puerto. | `3000` | No |
| `CORS_ALLOWED_ORIGINS` | Orígenes CORS permitidos, separados por comas. En production/staging, solo se aceptan orígenes `https://` y se rechazan los orígenes localhost. | `http://localhost:3000` | No |
| `TRUSTED_PROXIES` | IPs/CIDRs de proxy, separados por comas, autorizados para establecer la IP real del cliente. | — | No |
## Autenticación
Lerian SPB delega la autorización, incluida la API de administración de systemplane, en Access Manager. Consulta [Fundamentos de configuración de BYOC](/es/reference/byoc-configuration#plugin-authentication).
| Variable | Descripción | Predeterminado | Obligatorio |
| --------------------- | ----------------------------------------------------------------- | ----------------------- | ------------------ |
| `PLUGIN_AUTH_ENABLED` | Requiere autenticación de Access Manager en las rutas protegidas. | `true` | No |
| `PLUGIN_AUTH_ADDRESS` | Dirección del servicio de Access Manager. | `http://localhost:4000` | Si está habilitado |
## PostgreSQL
| Variable | Descripción | Predeterminado | Obligatorio |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------- | --------------------- |
| `POSTGRES_HOST` | Host principal de PostgreSQL. | `localhost` | Sí |
| `POSTGRES_PORT` | Puerto principal de PostgreSQL. | `5432` | No |
| `POSTGRES_USER` | Usuario de la base de datos. | — | Sí |
| `POSTGRES_PASSWORD` | Contraseña de la base de datos. Sensible: inyéctala en el momento del despliegue; nunca la incluyas en un commit. | — | En production/staging |
| `POSTGRES_DB` | Nombre de la base de datos. | — | Sí |
| `POSTGRES_SSLMODE` | Modo TLS de libpq. Debe ser `verify-full` en production/staging. | `require` | No |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexiones inactivas. | `10` | No |
| `POSTGRES_CONN_MAX_LIFETIME` | Vida máxima de la conexión (duración de Go, por ejemplo `5m`). | `5m` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME` | Tiempo máximo de inactividad de la conexión (duración de Go). | `2m` | No |
### Réplica de PostgreSQL
Réplica de lectura opcional. Todos los campos recurren al primario cuando no están configurados.
| Variable | Descripción | Predeterminado | Obligatorio |
| --------------------------- | ----------------------------------------------------------------------------------------------------- | -------------- | ----------- |
| `POSTGRES_REPLICA_HOST` | Host de la réplica. Sin configurar = sin réplica. | — | No |
| `POSTGRES_REPLICA_PORT` | Puerto de la réplica. | — | No |
| `POSTGRES_REPLICA_USER` | Usuario de la réplica. | — | No |
| `POSTGRES_REPLICA_PASSWORD` | Contraseña de la réplica. Sensible. | — | No |
| `POSTGRES_REPLICA_DB` | Nombre de la base de datos de la réplica. | — | No |
| `POSTGRES_REPLICA_SSLMODE` | Modo TLS de la réplica. Debe ser `verify-full` en production/staging cuando se configura una réplica. | — | No |
## Redis
| Variable | Descripción | Predeterminado | Obligatorio |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------------------- |
| `REDIS_HOST` | Host de Redis. Debe ser explícito y no local en production/staging. | `localhost` | En production/staging |
| `REDIS_PORT` | Puerto de Redis. | `6379` | No |
| `REDIS_PASSWORD` | Contraseña de Redis. Sensible. | — | En production/staging |
| `REDIS_DB` | Número de base de datos de Redis. | `0` | No |
| `REDIS_TLS_ENABLED` | Habilita TLS hacia Redis. Debe ser `true` en production/staging. | `false` | En production/staging |
| `REDIS_TLS_CA_CERT_BASE64` | Certificado de CA codificado en Base64 para TLS de Redis. Obligatorio cuando `REDIS_TLS_ENABLED=true` en production/staging. | — | Si TLS está habilitado |
| `REDIS_POOL_SIZE` | Tamaño del pool de conexiones. | `20` | No |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexiones inactivas. | `5` | No |
## Conectividad STR (RSFN)
Lerian SPB intercambia mensajes STR con BACEN a través de la RSFN usando un transporte IBM MQ. Estas variables definen la identidad del participante, la conexión al gestor de colas y las colas.
| Variable | Descripción | Predeterminado | Obligatorio |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------- |
| `STR_ISPB` | El ISPB de 8 dígitos del participante. En production/staging debe ser un ISPB real explícito, no `00000000`. | `00000000` | En production/staging |
| `SILOC_ISPB` | El ISPB de 8 dígitos de la câmara SILOC, resuelto en el servidor para los mensajes de liquidación relacionados con SILOC, nunca proporcionado por el cliente. En production/staging debe ser un ISPB de câmara de 8 dígitos explícito, no `00000000`. | `02992335` | No |
| `STR_MQ_HOST` | Host del gestor de colas. | — | Sí (STR en vivo) |
| `STR_MQ_PORT` | Puerto de escucha del gestor de colas. | `1414` | No |
| `STR_MQ_CHANNEL` | Canal de conexión de servidor de MQ. | `DEV.APP.SVRCONN` | No |
| `STR_MQ_QUEUE_MGR` | Nombre del gestor de colas. | `QM1` | No |
| `STR_MQ_USER` | Usuario de conexión de MQ. | `app` | No |
| `STR_MQ_PASSWORD` | Contraseña de conexión de MQ. Sensible. | — | En production/staging |
| `STR_MQ_TLS_ENABLED` | Habilita TLS mutuo en el canal de MQ. Obligatorio para una conexión STR real. | `false` | En production/staging |
| `MQSSLKEYR` | Ruta al repositorio de claves de GSKit que respalda TLS de MQ. La clave privada vive aquí, nunca en una variable de entorno. | — | Si TLS está habilitado |
| `STR_MQ_SEND_QUEUE` | Cola de solicitudes salientes. Se deriva de `STR_ISPB` cuando no está configurada. | Derivado | No |
| `STR_MQ_RESPONSE_QUEUE` | Cola de respuestas. Se deriva de `STR_ISPB` cuando no está configurada. | Derivado | No |
| `STR_MQ_RECEIVE_QUEUE` | Cola de recepción entrante. Se deriva de `STR_ISPB` cuando no está configurada. | Derivado | No |
| `MQ_HEARTBEAT_INTERVAL` | Intervalo de heartbeat de MQ (duración de Go). | `300s` | No |
| `MQ_DISCONNECT_INTERVAL` | Intervalo de desconexión de MQ (duración de Go). | `6000s` | No |
| `MQ_SEQ_WRAP` | Techo de reinicio de secuencia de mensajes para el canal de MQ. | `99999999` | No |
| `MQ_ADOPTNEWMCA` | Configuración `AdoptNewMCA` del canal de MQ. | `ALL` | No |
### Circuit breaker
Protege el transporte STR frente a un gestor de colas con fallas.
| Variable | Descripción | Predeterminado | Obligatorio |
| ------------------------- | ------------------------------------------------------------------------------ | -------------- | ----------- |
| `CB_MAX_REQUESTS` | Solicitudes permitidas mientras el breaker está en half-open. | `3` | No |
| `CB_INTERVAL` | Ventana móvil sobre la que se cuentan las fallas (duración de Go). | `30s` | No |
| `CB_TIMEOUT` | Tiempo de espera de recuperación del estado open (duración de Go). | `10s` | No |
| `CB_CONSECUTIVE_FAILURES` | Fallas consecutivas antes de que el breaker se dispare. | `5` | No |
| `CB_FAILURE_RATIO` | Proporción de fallas que dispara el breaker (0-1). | `0.5` | No |
| `CB_MIN_REQUESTS` | Mínimo de solicitudes en una ventana antes de que el breaker pueda dispararse. | `10` | No |
## Firma de mensajes y certificados
Lerian SPB firma cada mensaje STR. Elige el backend de custodia de claves con `SPB_SIGNER_KIND`. Production y staging rechazan el backend `file` y requieren una clave respaldada por hardware (`pkcs11` o `kmip`).
| Variable | Descripción | Predeterminado | Obligatorio |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------- |
| `SPB_SIGNER_KIND` | Backend de custodia de firma: `file`, `pkcs11` o `kmip`. `file` solo se permite cuando `ENV_NAME=develop`; production y staging lo rechazan. (`hsm` y `kms` están declarados pero no implementados). | `file` | No |
| `CERT_BASE_PATH` | Directorio base para el material de certificados. | `/certs` | No |
| `CERT_PATH` | Ruta al certificado de firma. | — | En production/staging |
| `KEY_PATH` | Ruta a la clave privada de firma. | — | En production/staging |
| `PROCESS_CERT_PATH` | Ruta al certificado de proceso/TLS. | — | En production/staging |
| `PROCESS_PRIVATE_KEY_PATH` | Ruta a la clave privada de proceso/TLS. Sensible. | — | No |
| `BACEN_PUBLIC_CERT_PATH` | Ruta al certificado público de BACEN, usado para verificar las firmas entrantes y para el cifrado de SFN. | — | En production/staging |
| `CERT_READINESS_MIN_DAYS` | Días mínimos hasta el vencimiento antes de que la verificación de readiness del certificado reporte degradado. | `30` | No |
### Custodia PKCS#11
Obligatorio cuando `SPB_SIGNER_KIND=pkcs11`.
| Variable | Descripción | Predeterminado | Obligatorio |
| ------------------------ | ---------------------------------------------------------- | -------------- | -------------- |
| `SPB_PKCS11_MODULE_PATH` | Ruta a la biblioteca del módulo PKCS#11. | — | Si es `pkcs11` |
| `SPB_PKCS11_TOKEN_LABEL` | Etiqueta del token PKCS#11. | — | Si es `pkcs11` |
| `SPB_PKCS11_PIN_FILE` | Ruta a un archivo que contiene el PIN del token. Sensible. | — | Si es `pkcs11` |
| `SPB_PKCS11_KEY_LABEL` | Etiqueta de la clave de firma en el token. | — | Si es `pkcs11` |
### Custodia KMIP
Obligatorio cuando `SPB_SIGNER_KIND=kmip` (KMIP sobre HTTP hacia un HSM de red).
| Variable | Descripción | Predeterminado | Obligatorio |
| ------------------------------- | -------------------------------------------------------------------------- | -------------- | ------------ |
| `SPB_KMIP_BASE_URL` | URL base del servicio KMIP. | — | Si es `kmip` |
| `SPB_KMIP_VHSM` | Identificador del HSM virtual. | — | Si es `kmip` |
| `SPB_KMIP_CRYPTO_USER` | Usuario criptográfico de KMIP. | — | Si es `kmip` |
| `SPB_KMIP_CRYPTO_USER_TOKEN` | Token de usuario criptográfico de KMIP. Sensible. | — | Si es `kmip` |
| `SPB_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma. | — | Si es `kmip` |
| `SPB_KMIP_SIGN_PUBLIC_KEY_UID` | UID de la clave pública de firma. | — | Si es `kmip` |
| `SPB_KMIP_DECRYPT_KEY_UID` | UID de la clave de descifrado usada en la ruta de descifrado entrante. | — | No |
| `SPB_KMIP_DIGEST_INFO_PREFIX` | Antepone el prefijo ASN.1 DigestInfo antes de la llamada de firma de KMIP. | `false` | No |
## Eventos, outbox y RabbitMQ
Lerian SPB registra cada mensaje antes de enviarlo y publica eventos de ciclo de vida a través de un outbox transaccional hacia RabbitMQ.
| Variable | Descripción | Predeterminado | Obligatorio |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------- |
| `EMISSION_REQUIRED` | Cuando es `true`, el arranque falla de forma cerrada a menos que la emisión de eventos esté completamente configurada. | `false` | No |
| `RABBITMQ_HOST` | Host de RabbitMQ. | — | Sí (eventos) |
| `RABBITMQ_PORT` | Puerto de RabbitMQ. | `5672` | No |
| `RABBITMQ_USER` | Usuario de RabbitMQ. No debe ser el `guest` predeterminado en production/staging. | `guest` | En production/staging |
| `RABBITMQ_PASSWORD` | Contraseña de RabbitMQ. Sensible. No debe estar vacía ni ser la predeterminada en production/staging. | `guest` | En production/staging |
| `RABBITMQ_VHOST` | Host virtual de RabbitMQ. | `/` | No |
| `RABBITMQ_STR_EXCHANGE` | Nombre del exchange para los eventos de ciclo de vida de STR. | `str.events` | No |
| `RABBITMQ_TLS_ENABLED` | Habilita TLS hacia RabbitMQ. Debe ser `true` en production/staging cuando se configura un host. | `false` | En production/staging |
| `OUTBOX_DISPATCH_INTERVAL` | Intervalo entre ciclos de envío del outbox (duración de Go). | `2s` | No |
| `OUTBOX_BATCH_SIZE` | Filas drenadas por ciclo de envío. | `50` | No |
| `OUTBOX_MAX_PUBLISH_ATTEMPTS` | Máximo de intentos de reintento del publicador de RabbitMQ para cada llamada de publicación. El agotamiento de la entrega de webhooks se rige por separado mediante `EVENT_DELIVERY_MAX_ATTEMPTS`. | `3` | No |
| `OUTBOX_POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas para el pool del outbox. | `10` | No |
| `OUTBOX_POSTGRES_MAX_IDLE_CONNS` | Máximo de conexiones inactivas para el pool del outbox. | `5` | No |
| `EVENT_DELIVERY_BATCH_SIZE` | Eventos entregados por ciclo. | `25` | No |
| `EVENT_DELIVERY_MAX_ATTEMPTS` | Intentos de entrega antes de que un evento quede retenido. | `3` | No |
| `EVENT_DELIVERY_RETRY_BACKOFF` | Backoff base entre reintentos de entrega (duración de Go). | `30s` | No |
| `DISPATCH_MAX_AUTO_ATTEMPTS` | Intentos de envío automático antes de la intervención manual. | `8` | No |
| `DISPATCH_RETRY_BACKOFF_CEILING` | Backoff máximo entre reintentos de envío (duración de Go). | `30m` | No |
| `LDL_ADVISORY_CONSUMER_ENABLED` | Habilita el consumidor supervisado de los datos informativos de liquidación OT de SILOC. Requiere `STREAMING_BROKERS` y persistencia duradera cuando está habilitado, y se niega a empezar sin ellos. El tema y el grupo del consumidor están fijos en el servicio; ninguno de los dos es configurable a través del entorno. La conexión al broker proviene de la configuración compartida `STREAMING_*` (consulta [Streaming y outbox](/es/reference/byoc-configuration#streaming-and-outbox)). Deshabilitado, su verificación de readiness reporta `skipped`. | `false` | No |
## Aprobación (maker-checker)
Aprobación opcional por banda de valor que condiciona la emisión de STR. Deshabilitada de forma predeterminada. Una tabla de bandas vacía deja que toda emisión avance en un solo paso.
| Variable | Descripción | Predeterminado | Obligatorio |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------- |
| `APPROVAL_ALCADA_BANDS` | Bandas `maxExclusive:requiredSignatures` separadas por punto y coma (por ejemplo, `10000.00:1;100000.00:2`). Vacío mantiene la aprobación deshabilitada. | — | No |
| `APPROVAL_DEADLINE_WINDOW` | Cuánto tiempo puede esperar una emisión retenida (duración de Go, con un límite de 7 días). | `24h` | No |
| `APPROVAL_EXPIRY_ENABLED` | Ejecuta el barrido en segundo plano que vence las emisiones retenidas vencidas. | `true` | No |
| `APPROVAL_EXPIRY_SWEEP_INTERVAL` | Intervalo del barrido (duración de Go). | `1m` | No |
## Rate limiting e idempotencia
| Variable | Descripción | Predeterminado | Obligatorio |
| ----------------------------- | ------------------------------------------------------------------ | -------------- | ----------- |
| `RATE_LIMIT_IP_MAX` | Máximo de solicitudes por IP y por ventana. | `300` | No |
| `RATE_LIMIT_IP_WINDOW` | Ventana de rate limit por IP (duración de Go). | `1m` | No |
| `RATE_LIMIT_KEY_MAX` | Máximo de solicitudes por clave de API y por ventana. | `100` | No |
| `RATE_LIMIT_KEY_WINDOW` | Ventana de rate limit por clave (duración de Go). | `1m` | No |
| `IDEMPOTENCY_ENABLED` | Habilita la deduplicación por clave de idempotencia. | `true` | No |
| `IDEMPOTENCY_DEFAULT_TTL_SEC` | Cuánto tiempo (en segundos) se conserva una clave de idempotencia. | `300` | No |
## Systemplane y configuración en runtime
Lerian SPB monta la API de administración de configuración en runtime de systemplane en `/v1/system` en el puerto principal. PostgreSQL respalda este plano, de modo que los operadores pueden leer y cambiar la configuración recargable en caliente sin un reinicio. Consulta [Systemplane](/es/reference/platform/systemplane/overview) para conocer la API, los namespaces y los permisos.
| Variable | Descripción | Predeterminado | Obligatorio |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------- |
| `SYSTEMPLANE_LISTEN_CHANNEL` | Canal `LISTEN`/`NOTIFY` de PostgreSQL al que se suscribe el plano de configuración en runtime para los cambios de configuración en caliente. | Predeterminado del servicio | No |
## Cifrado y secretos
| Variable | Descripción | Predeterminado | Obligatorio |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | --------------------- |
| `STR_PAYLOAD_ENCRYPTION_KEY` | Clave AES-256 codificada en Base64 para el cifrado en reposo de los payloads STR almacenados. Sensible. Obligatoria en production/staging. | — | En production/staging |
| `WEBHOOK_SECRET_KEY` | Clave usada para cifrar los secretos de webhook almacenados. Sensible. Obligatoria en production/staging. | — | En production/staging |
| `INBOUND_ALLOW_CLEARTEXT_FALLBACK` | Permite que la ruta entrante acepte payloads sin cifrar. Deja `false` en production y staging. | `false` | No |
Nunca subas a un commit ni registres en logs los valores de ninguna variable marcada como *Sensible* (contraseñas, tokens, PINs y claves AES). Inyéctalas en el momento del despliegue a través de tu gestor de secretos.
## Observabilidad
| Variable | Descripción | Predeterminado | Obligatorio |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------- | -------------------------------- |
| `ENABLE_TELEMETRY` | Habilita el trazado y las métricas de OpenTelemetry. | `false` | En production/staging |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. Debe usar `https://` en production/staging. | `http://localhost:4318` | Si la telemetría está habilitada |
| `OTEL_RESOURCE_SERVICE_NAME` | Nombre del servicio adjunto a la telemetría exportada. | Predeterminado del servicio | No |
| `METRICS_PROMETHEUS_ENABLED` | Expone un endpoint de scraping de Prometheus dedicado. | `false` | No |
| `METRICS_PROMETHEUS_ADDRESS` | Dirección de escucha para el endpoint de Prometheus. Se vincula a loopback de forma predeterminada. | `127.0.0.1:9090` | No |
## Solo para desarrollo
Mantén estas variables sin configurar fuera del desarrollo local. Amplían la superficie de ataque, y production o staging las rechaza o las fuerza a estar deshabilitadas.
| Variable | Descripción | Predeterminado | Obligatorio |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------------------------------- |
| `ENABLE_DEV_DEBUG_ROUTES` | Expone las rutas de depuración. Prohibido en production/staging. | `false` | No |
| `DEV_DEBUG_TOKEN` | Token que protege las rutas de depuración. Sensible. Obligatorio cuando las rutas de depuración están habilitadas. | — | Si la depuración está habilitada |
| `SWAGGER_ENABLED` | Sirve la especificación OpenAPI y la interfaz de documentación de la API. Forzado a deshabilitado en production y staging. | `false` | No |
| `STR_MQ_MOCK` | Enruta el transporte STR hacia un mock en lugar de un gestor de colas en vivo. | `false` | No |
| `STR_MQ_MOCK_HOST` | Host del mock de STR. Obligatorio cuando `STR_MQ_MOCK=true`. | `http://localhost:8080` | Si el mock está habilitado |
| `STR_MQ_MOCK_ALLOWED_HOSTS` | Lista de hosts permitidos que el transporte mock puede alcanzar. | — | No |
| `ALLOW_MOCK_TRANSPORT` | Permite que el transporte mock se pueda seleccionar. | `false` | No |
## Salud y readiness
Lerian SPB expone `GET /health` (liveness) y `GET /readyz` (readiness) en el puerto HTTP principal. Consulta [Salud y readiness](/es/reference/health-and-readiness) para conocer el contrato de las sondas.