Variables de entorno

Lerian SILOC es la integración de mensajería nativa de Lerian para SILOC, el sistema de liquidación diferida neta que Núclea opera para los flujos de boleto y tarjetas. Estableces estas variables en el momento del despliegue. Un cambio surte efecto solo después de que reinicies el servicio. Para conocer los parámetros que se comportan igual en todos los servicios de Lerian en Go (postura de despliegue, telemetría y convenciones de almacenamiento de datos), consulta Fundamentos de configuración de BYOC. En las siguientes tablas, Obligatorio marca una variable que debes establecer, ya sea de forma global o bajo la condición indicada. — significa que no hay valor predeterminado.

Runtime y servidor

Variable	Descripción	Predeterminado	Obligatorio
`SERVICE_NAME`	Identificador del servicio usado en los logs y la telemetría.	Predeterminado del servicio	No
`ENV_NAME`	Etiqueta del entorno de runtime. `production` o `prod` activa las verificaciones más estrictas de autenticación y TLS que se describen abajo.	`development`	No
`DEPLOYMENT_MODE`	Postura de aplicación de TLS (`local`, `byoc`, `saas`). `saas` hace que TLS sea obligatorio, exige un `ENV_NAME` de producción, y el servicio se niega a iniciar sin ellos. Consulta Modo de despliegue y TLS.	—	No
`LOG_LEVEL`	Nivel de verbosidad de los logs (`debug`, `info`, `warn`, `error`).	`info`	No
`SERVER_PORT`	Puerto de escucha HTTP. Las sondas de liveness y readiness se vinculan a este mismo puerto.	`9820`	No
`IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY`	Clave AES-256 que cifra las respuestas que el servicio guarda para las repeticiones de `X-Idempotency`: 32 bytes en bruto, o su forma en base64. Sensible.	—	Sí

Autenticación

Lerian SILOC autoriza las rutas protegidas mediante Access Manager. AUTH_ENABLED no tiene valor predeterminado, así que el servicio se niega a iniciar hasta que lo establezcas.

Variable	Descripción	Predeterminado	Obligatorio
`AUTH_ENABLED`	Exige la autorización de Access Manager en las rutas protegidas: `true` o `false`. El servicio acepta `false` solo cuando estableces `ENV_NAME` en `development`, `develop`, `dev`, `local` o `test`, y nunca con `DEPLOYMENT_MODE=saas`. Con `false`, el servicio omite la llamada a Access Manager, pero sigue exigiendo un token bearer.	—	Sí
`AUTH_ADDRESS`	Dirección del servicio Access Manager. Debe ser una URL `https://` válida en producción y SaaS. Con la autorización activa y sin dirección, las rutas protegidas responden 503.	—	En producción y SaaS

PostgreSQL

La réplica recurre al host primario cuando dejas DB_REPLICA_HOST vacío (predeterminado de nodo único).

Variable	Descripción	Predeterminado	Obligatorio
`DB_HOST`	Host de PostgreSQL.	—	Sí (en vivo)
`DB_PORT`	Puerto de PostgreSQL.	`5432`	No
`DB_USER`	Usuario de la base de datos.	—	Sí (en vivo)
`DB_PASSWORD`	Contraseña de la base de datos. Sensible. Inyéctala en el momento del despliegue y nunca la incluyas en un commit.	—	Sí (en vivo)
`DB_NAME`	Nombre de la base de datos.	—	Sí (en vivo)
`DB_SSLMODE`	Modo TLS de libpq. Un modo distinto de `require`, `verify-ca` o `verify-full` requiere `ALLOW_INSECURE_TLS=true`.	`disable`	No
`DB_REPLICA_HOST`	Host opcional de réplica de lectura. Recurre a `DB_HOST` cuando no está establecido.	—	No

Redis

Variable	Descripción	Predeterminado	Obligatorio
`REDIS_ADDRESS`	Host y puerto de Redis/Valkey. La puerta de `X-Idempotency` guarda aquí sus claves, así que las solicitudes que cambian el estado y el readiness lo necesitan.	—	Sí (en vivo)
`REDIS_PASSWORD`	Contraseña de Redis. Sensible.	—	No
`REDIS_DB`	Número de base de datos de Redis. Un valor que no sea entero impide el arranque.	`0`	No
`REDIS_TLS`	Abre la conexión con Redis sobre TLS. `DEPLOYMENT_MODE=saas` exige `true`.	`false`	No
`REDIS_CA_CERT`	Autoridad certificadora PEM codificada en base64 que valida el servidor Redis cuando `REDIS_TLS=true`. Cuando está vacía, el servicio usa las autoridades de confianza del sistema operativo.	—	No
`ALLOW_INSECURE_TLS`	Establece true para que el servicio abra conexiones con PostgreSQL y Redis sin TLS. El servicio registra una advertencia mientras esta excepción está activa.	—	No

Conectividad de liquidación de SILOC

Lerian SILOC mantiene una única conexión IBM MQ con el gestor de colas de liquidación de SILOC de Núclea. Establecer MQ_HOST, MQ_CHANNEL, MQ_QUEUE_MANAGER, MQ_SEND_QUEUE o MQ_RECEIVE_QUEUE hace que el servicio valide todo el descriptor de conexión de forma cerrada en el arranque. Las demás variables MQ_* por sí solas no activan esa validación.

Variable	Descripción	Predeterminado	Obligatorio
`LOCAL_FI_ISPB`	El ISPB de 8 dígitos de esta institución. Cada mensaje OT se autoriza contra él. Con MQ configurado, debe coincidir con el ISPB de `MQ_CHANNEL`.	—	Sí
`MQ_HOST`	Host del gestor de colas.	—	Sí (SILOC en vivo)
`MQ_PORT`	Puerto de escucha del gestor de colas.	—	Sí (SILOC en vivo)
`MQ_QUEUE_MANAGER`	Nombre del gestor de colas. Debe ser el gestor de colas de liquidación de SILOC de Núclea.	—	Sí (SILOC en vivo)
`MQ_CHANNEL`	Canal de conexión de servidor. Debe coincidir con el patrón de canal de SILOC de Núclea `C02992335.<ISPB>.1`, donde `<ISPB>` es el ISPB de 8 dígitos del participante.	—	Sí (SILOC en vivo)
`MQ_SEND_QUEUE`	Cola de envío saliente.	—	Sí (SILOC en vivo)
`MQ_RECEIVE_QUEUE`	Cola de recepción entrante.	—	Sí (SILOC en vivo)
`MQ_BACKOUT_THRESHOLD`	Cuántas veces el servicio puede rechazar un frame entrante antes de aparcarlo en su base de datos y retirarlo de la cola de recepción. Un entero de 1 a 1000.	—	Sí (SILOC en vivo)
`MQ_BACKOUT_DELAY`	Pausa antes de que un frame rechazado se entregue de nuevo, como una duración con unidad, de `100ms` a `1m` (por ejemplo, `2s`).	—	Sí (SILOC en vivo)
`MQ_TLS_ENABLED`	Habilita TLS mutuo en el canal MQ. Debe ser `true` en producción y SaaS.	`false`	En producción y SaaS
`MQ_SSL_KEY_REPOSITORY`	Ruta al repositorio de claves de GSKit (`MQSSLKEYR`) que respalda TLS de MQ. La clave privada vive aquí, nunca en una variable de entorno. Obligatoria cuando `MQ_TLS_ENABLED=true`.	—	Si TLS está habilitado
`MQ_CIPHER_SPEC`	Especificación de cifrado TLS del canal MQ cuando `MQ_TLS_ENABLED=true`. Debe coincidir con la especificación de cifrado del canal de conexión de servidor en el gestor de colas.	`ECDHE_RSA_AES_256_CBC_SHA384`	No
`MQ_CERT_LABEL`	Etiqueta del certificado en el repositorio de claves que el servicio presenta en el canal MQ cuando `MQ_TLS_ENABLED=true`. Cuando está vacía, el cliente MQ usa su etiqueta predeterminada.	—	No
`CAMARA_PAG_ISPB`	El ISPB de 8 dígitos de la câmara de SILOC. Cada mensaje de liquidación entrante se autoriza contra este remitente antes de tener cualquier efecto semántico. Coincide con el prefijo del canal de liquidación, así que anúlalo solo para una câmara de prueba. Un valor que no tenga 8 dígitos impide el arranque.	`02992335`	No

Mensajes salientes

El servicio envía las solicitudes de la institución a Núclea solo cuando los dos identificadores de certificado y MQ_SEND_QUEUE están establecidos. Establece los dos identificadores o ninguno: uno sin el otro impide el arranque.

Variable	Descripción	Predeterminado	Obligatorio
`SFN_OUTBOUND_SIGNER_CERT_ID`	El certificado que firma los mensajes salientes, con el formato `<authority>:<64 hex>`. El proveedor de custodia guarda su clave. Un valor que no se puede interpretar impide que el servicio arranque.	—	Para enviar
`SFN_CAMARA_CERT_ID`	El certificado de la câmara, del manifiesto de confianza, al que se cifran los mensajes salientes, con el mismo formato. Un valor que no se puede interpretar impide que el servicio arranque.	—	Para enviar
`OT_OUTBOUND_DISPATCH_INTERVAL`	Con qué frecuencia el despachador pone los mensajes enviados en la cola de envío.	`5s`	No
`UNANSWERED_REQUEST_DEADLINES`	Cuánto tiempo espera una solicitud despachada su respuesta antes de que el servicio genere `UNANSWERED_REQUEST`, con el formato `default=<duration>,<COD_MSG>=<duration>`. Sin establecer, las consultas esperan 2 minutos, las confirmaciones 5 y los comandos 15. El mínimo es 1 segundo.	—	No
`UNANSWERED_REQUEST_SWEEP_INTERVAL`	Con qué frecuencia el servicio busca solicitudes sin respuesta, de `1s` a `10m`.	`30s`	No

Validación de mensajes

El servicio valida los mensajes entrantes que aplica y los mensajes salientes que envía contra los esquemas XSD oficiales, mediante un sidecar validador.

Variable	Descripción	Predeterminado	Obligatorio
`XSD_VALIDATOR_URL`	URL base del sidecar validador.	—	Sí (SILOC en vivo)
`XSD_VALIDATOR_TIMEOUT_SEC`	Tiempo de espera de una solicitud de validación, en segundos. Un valor que no sea entero impide el arranque.	`10`	No

El sidecar escucha en XSD_VALIDATOR_ADDR (predeterminado 127.0.0.1:9091), y su propio AUTH_ENABLED no tiene valor predeterminado. El servicio no envía ningún token bearer al sidecar, así que ejecuta el sidecar con AUTH_ENABLED=false en una dirección de loopback literal.

Certificados

Variable	Descripción	Predeterminado	Obligatorio
`CERT_READINESS_MIN_DAYS`	Umbral de días para el vencimiento por debajo del cual un certificado actualmente válido registra una advertencia y genera una alerta `CERTIFICATE_EXPIRY`. No degrada el readiness únicamente porque el certificado esté cerca de vencer. Debe ser un entero mayor que 0.	`30`	No

Confianza y custodia

Variable	Descripción	Predeterminado	Obligatorio
`SFN_TRUST_MANIFEST_PATH`	Ruta al manifiesto de confianza de SFN usado para validar el material de confianza de los mensajes regulados. Sin ella, el servicio informa que no está listo.	—	Sí (SILOC en vivo)
`SFN_CUSTODY_CONFIG_PATH`	Ruta a la configuración del proveedor de custodia. Sin ella, el servicio informa que no está listo.	—	Sí (SILOC en vivo)
`SFN_CUSTODY_CACHE_ENTRIES`	Número máximo de entradas de custodia que se mantienen en la caché en memoria. Un valor que no sea entero impide el arranque.	`16`	No

Procesamiento en segundo plano

Los cinco interruptores *_ENABLED de esta tabla no tienen valor predeterminado. Establece cada uno en true o false, porque un valor vacío impide el arranque. Con false, el runtime queda apagado y su verificación de readiness reporta skipped. Con true, el servicio reintenta un runtime que no arranca hasta que se ejecute, y su verificación de readiness reporta el motivo sin fallar.

Variable	Descripción	Predeterminado	Obligatorio
`OT_REPLAY_ENABLED`	Aplica los mensajes entrantes aparcados, excepto `PAG0101`: mensajes de ciclo OT, avisos de la câmara y respuestas a las solicitudes de la institución. Con `true`, la conexión MQ de SILOC (`MQ_HOST` y el resto de `MQ_*`) debe estar configurada, o el servicio se niega a arrancar y nombra los dos ajustes.	—	Sí
`OT_REPLAY_INTERVAL`	Con qué frecuencia se ejecuta la repetición de OT.	`10s`	No
`STATUS_REPLAY_ENABLED`	Aplica los mensajes de estado de participante `PAG0101` aparcados.	—	Sí
`STATUS_REPLAY_INTERVAL`	Con qué frecuencia se ejecuta la repetición de estado.	`10s`	No
`RECONCILE_ENABLED`	Concilia los ciclos OT con el resultado multilateral `GEN0015` de la câmara y liquida un ciclo cuyo resultado coincide con su obligación.	—	Sí
`RECONCILE_INTERVAL`	Con qué frecuencia se ejecuta la conciliación.	`10s`	No
`LDL_FACT_CONSUMER_ENABLED`	Consume los hechos de liquidación LDL de SPB. Cada hecho registra el resultado de la instrucción que nombra.	—	Sí
`CARD_COMMAND_CONSUMER_ENABLED`	Consume comandos de tarjeta de Lerian SLC y los envía a Núclea.	—	Sí

Declaración de permisos

El servicio puede publicar su propio conjunto de permisos en Access Manager durante el arranque. Solo IDP_DECLARATION_ENABLED=true lo activa. Con la publicación activa, una variable faltante de las siguientes impide el arranque.

Variable	Descripción	Predeterminado	Obligatorio
`IDP_DECLARATION_ENABLED`	Publica el conjunto de permisos durante el arranque.	`false`	No
`IDP_HOST`	URL base de Access Manager a la que se publica el conjunto. Debe ser `https://` fuera de los entornos locales y de desarrollo.	—	Con declaración
`IDP_M2M_CLIENT_ID`	Client ID de la aplicación máquina a máquina del servicio, cuyo nombre debe ser `siloc`.	—	Con declaración
`IDP_M2M_CLIENT_SECRET`	Client secret de esa aplicación. Sensible.	—	Con declaración
`PLUGIN_AUTH_ENABLED`	Debe ser `true` para que el servicio obtenga el token que usa la publicación. No controla la autorización de las rutas, que controla `AUTH_ENABLED`.	—	Con declaración
`PLUGIN_AUTH_HOST`	Dirección de Access Manager para ese token.	—	Con declaración

Observabilidad

Variable	Descripción	Predeterminado	Obligatorio
`ENABLE_TELEMETRY`	Habilita la instrumentación de OpenTelemetry.	`false`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del colector OTLP.	—	Si la telemetría está habilitada
`STREAMING_BROKERS`	Direcciones de broker para el despachador de hechos obligatorio de SILOC. El streaming no tiene modo deshabilitado: una configuración de broker faltante o inválida impide el arranque, en lugar de dejar los hechos como `PENDING`. Configura los ajustes compartidos `STREAMING_*` como se describe en Streaming y outbox.	—	Sí
`STREAMING_CLOUDEVENTS_SOURCE`	Identidad de origen de CloudEvents. Debe ser exactamente `br-siloc`. Un valor diferente, incluidos espacios en blanco al inicio o al final, impide el arranque; el servicio usa esa identidad para derivar sus temas de broker y el ámbito de control de acceso.	—	Sí

Si STREAMING_EVENT_POLICIES define enabled=false para un evento de comando de tarjeta (siloc_command.accepted, siloc_command.answered, siloc_command.refused o siloc_command.failed), el consumidor de comandos de tarjeta no arranca. Si define enabled=false para siloc.relay.inbound, el procesamiento de mensajes entrantes no arranca. En ambos casos, el error nombra el evento.

Salud y readiness

Lerian SILOC expone GET /health (liveness), GET /readyz (readiness) y GET /version en el puerto HTTP principal. El servicio se niega a arrancar cuando PostgreSQL no responde en un plazo de 10 segundos. Arranca antes de que Redis y la conexión de liquidación sean accesibles. /readyz reporta la salud de cada dependencia. Mientras el queue manager de SILOC de Núclea no es accesible, siloc-mq reporta down y no hace que /readyz pase a 503. siloc-mq hace fallar el readiness cuando el queue manager rechaza la configuración de esta implementación, y nombra el ajuste que hay que corregir. Consulta Salud y readiness para conocer el contrato de las sondas.

​Runtime y servidor

​Autenticación

​PostgreSQL

​Redis

​Conectividad de liquidación de SILOC

​Mensajes salientes

​Validación de mensajes

​Certificados

​Confianza y custodia

​Procesamiento en segundo plano

​Declaración de permisos

​Observabilidad

​Salud y readiness