Environment variables

Deploy-time environment variables for Lerian SILOC: runtime, SILOC settlement-queue connectivity, persistence, authentication, and certificates.

Lerian SILOC is Lerian’s native messaging integration for SILOC, the deferred-net settlement system that Núclea operates for boleto and card flows. You set these variables at deploy time. A change takes effect only after you restart the service. For the knobs that behave the same across every Lerian Go service (deployment posture, telemetry, and datastore conventions), see BYOC configuration essentials.

In the tables below, Required marks a variable you must set, globally or under the stated condition. — means no default.

Runtime and server

Variable	Description	Default	Required
SERVICE_NAME	Service identifier used in logs and telemetry.	Service default	No
ENV_NAME	Runtime environment label. production or prod arms the stricter authentication and TLS gates below.	development	No
DEPLOYMENT_MODE	TLS-enforcement posture (local, byoc, saas). saas makes TLS mandatory, requires a production ENV_NAME, and refuses to start without them. See Deployment mode and TLS.	—	No
LOG_LEVEL	Log verbosity (debug, info, warn, error).	info	No
SERVER_PORT	HTTP listen port. The liveness and readiness probes bind this same port.	9820	No
IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY	AES-256 key that encrypts the responses the service keeps for X-Idempotency replays: 32 raw bytes, or their base64 form. Sensitive.	—	Yes

Authentication

Lerian SILOC authorizes protected routes through Access Manager. AUTH_ENABLED has no default, so the service refuses to start until you set it.

Variable	Description	Default	Required
AUTH_ENABLED	Require Access Manager authorization on protected routes: true or false. The service accepts false only when you set ENV_NAME to development, develop, dev, local, or test, and never with DEPLOYMENT_MODE=saas. With false, the service skips the Access Manager call but still requires a bearer token.	—	Yes
AUTH_ADDRESS	Access Manager service address. Must be a valid https:// URL in production and SaaS. With authorization on and no address, protected routes answer 503.	—	In production and SaaS

PostgreSQL

The replica falls back to the primary host when you leave DB_REPLICA_HOST empty (single-node default).

Variable	Description	Default	Required
DB_HOST	PostgreSQL host.	—	Yes (live)
DB_PORT	PostgreSQL port.	5432	No
DB_USER	Database user.	—	Yes (live)
DB_PASSWORD	Database password. Sensitive. Inject it at deploy time and never commit it.	—	Yes (live)
DB_NAME	Database name.	—	Yes (live)
DB_SSLMODE	libpq TLS mode. A mode other than require, verify-ca, or verify-full needs ALLOW_INSECURE_TLS=true.	disable	No
DB_REPLICA_HOST	Optional read-replica host. Falls back to DB_HOST when unset.	—	No

Redis

Variable	Description	Default	Required
REDIS_ADDRESS	Redis/Valkey host and port. The X-Idempotency gate keeps its keys here, so state-changing requests and readiness need it.	—	Yes (live)
REDIS_PASSWORD	Redis password. Sensitive.	—	No
REDIS_DB	Redis database number.	0	No
REDIS_TLS	Sets the TLS posture reported by the Redis readiness check. It does not configure TLS for the Redis transport. DEPLOYMENT_MODE=saas requires true.	false	No
ALLOW_INSECURE_TLS	Set true to let the service open PostgreSQL and Redis connections without TLS. The service logs a warning while this override is on.	—	No

SILOC settlement connectivity

Lerian SILOC maintains a single IBM MQ connection to the Núclea SILOC settlement queue manager. Setting MQ_HOST, MQ_CHANNEL, MQ_QUEUE_MANAGER, MQ_SEND_QUEUE, or MQ_RECEIVE_QUEUE makes the service validate the whole connection descriptor fail-closed at startup. The other MQ_* variables alone do not activate that validation.

Variable	Description	Default	Required
LOCAL_FI_ISPB	This institution’s 8-digit ISPB. Every OT message is authorized against it. With MQ configured, it must match the ISPB in MQ_CHANNEL.	—	Yes
MQ_HOST	Queue-manager host.	—	Yes (live SILOC)
MQ_PORT	Queue-manager listener port.	—	Yes (live SILOC)
MQ_QUEUE_MANAGER	Queue-manager name. Must be the Núclea SILOC settlement queue manager.	—	Yes (live SILOC)
MQ_CHANNEL	Server-connection channel. Must match the Núclea SILOC channel pattern C02992335.<ISPB>.1, where <ISPB> is the participant’s 8-digit ISPB.	—	Yes (live SILOC)
MQ_SEND_QUEUE	Outbound send queue.	—	Yes (live SILOC)
MQ_RECEIVE_QUEUE	Inbound receive queue.	—	Yes (live SILOC)
MQ_BACKOUT_QUEUE	Queue that receives an inbound frame the service refused more than MQ_BACKOUT_THRESHOLD times. At most 48 characters, and different from MQ_SEND_QUEUE and MQ_RECEIVE_QUEUE.	—	Yes (live SILOC)
MQ_BACKOUT_THRESHOLD	How many times the service can refuse an inbound frame before it moves the frame to MQ_BACKOUT_QUEUE. An integer from 1 to 1000.	—	Yes (live SILOC)
MQ_BACKOUT_DELAY	Pause before a refused frame is delivered again, as a duration with a unit, from 100ms to 1m (for example, 2s).	—	Yes (live SILOC)
MQ_TLS_ENABLED	Enable mutual TLS on the MQ channel. Must be true in production and SaaS.	false	In production and SaaS
MQ_SSL_KEY_REPOSITORY	Path to the GSKit key repository (MQSSLKEYR) backing MQ TLS. The private key lives here, never in an environment variable. Required when MQ_TLS_ENABLED=true.	—	If TLS enabled
CAMARA_PAG_ISPB	The SILOC câmara’s 8-digit ISPB. Every inbound settlement message is authorized against this sender before it has any semantic effect. It matches the settlement channel prefix, so override it only for a test câmara. A value that is not 8 digits refuses to start.	02992335	No

Outbound messages

The service sends the institution’s requests to Núclea only when both certificate identifiers and MQ_SEND_QUEUE are set. Set both identifiers or neither: one without the other refuses to start.

Variable	Description	Default	Required
SFN_OUTBOUND_SIGNER_CERT_ID	The certificate that signs outbound messages, as <authority>:<64 hex>. The custody provider holds its key.	—	To send
SFN_CAMARA_CERT_ID	The câmara certificate, from the trust manifest, that outbound messages are encrypted to, in the same form.	—	To send
OT_OUTBOUND_DISPATCH_INTERVAL	How often the dispatcher puts submitted messages on the send queue.	5s	No
UNANSWERED_REQUEST_DEADLINES	How long a dispatched request waits for its answer before the service raises UNANSWERED_REQUEST, as default=<duration>,<COD_MSG>=<duration>. Unset, queries wait 2 minutes, confirmations 5, and commands 15. The minimum is 1 second.	—	No
UNANSWERED_REQUEST_SWEEP_INTERVAL	How often the service checks for unanswered requests, from 1s to 10m.	30s	No

Message validation

The service validates the inbound frames it applies and the outbound messages it sends against the official XSD schemas, through a validator sidecar.

Variable	Description	Default	Required
XSD_VALIDATOR_URL	Base URL of the validator sidecar.	—	Yes (live SILOC)
XSD_VALIDATOR_TIMEOUT_SEC	Timeout of one validation request, in seconds.	10	No

The sidecar listens on XSD_VALIDATOR_ADDR (default 127.0.0.1:9091), and its own AUTH_ENABLED has no default. The service sends no bearer token to the sidecar, so run the sidecar with AUTH_ENABLED=false on a literal loopback address.

Certificates

Variable	Description	Default	Required
CERT_READINESS_MIN_DAYS	Days-to-expiry threshold below which a currently valid certificate logs a warning and raises a CERTIFICATE_EXPIRY alert. It does not degrade readiness solely because the certificate is near expiry. Must be greater than 0.	30	No

Trust and custody

Variable	Description	Default	Required
SFN_TRUST_MANIFEST_PATH	Path to the SFN trust manifest used to validate regulated-message trust material. Without it, the service reports not ready.	—	Yes (live SILOC)
SFN_CUSTODY_CONFIG_PATH	Path to the custody-provider configuration. Without it, the service reports not ready.	—	Yes (live SILOC)
SFN_CUSTODY_CACHE_ENTRIES	Maximum number of custody entries kept in the in-memory cache.	16	No

Background processing

The five *_ENABLED switches in this table have no default. Set each one to true or false, because a blank value refuses to start. With false, the runtime stays off and its readiness check reports skipped. With true, the service retries a runtime that fails to start until it runs, and its readiness check reports the reason without failing.

Variable	Description	Default	Required
OT_REPLAY_ENABLED	Apply the parked inbound messages other than PAG0101: OT cycle messages, câmara advices and notices, and answers to the institution’s requests.	—	Yes
OT_REPLAY_INTERVAL	How often the OT replay runs.	10s	No
STATUS_REPLAY_ENABLED	Apply the parked PAG0101 participant-status messages.	—	Yes
STATUS_REPLAY_INTERVAL	How often the status replay runs.	10s	No
RECONCILE_ENABLED	Reconcile OT cycles against the câmara’s GEN0015 multilateral result, and settle a cycle whose result matches its obligation.	—	Yes
RECONCILE_INTERVAL	How often reconciliation runs.	10s	No
LDL_FACT_CONSUMER_ENABLED	Consume the SPB LDL settlement facts. Each fact records the outcome of the instruction it names.	—	Yes
CARD_COMMAND_CONSUMER_ENABLED	Consume card commands from Lerian SLC and send them to Núclea. Relay card deposit advisories to Lerian SPB.	—	Yes

Permission declaration

The service can publish its own permission set to Access Manager at startup. Only IDP_DECLARATION_ENABLED=true turns this on. With it on, a missing variable below refuses to start.

Variable	Description	Default	Required
IDP_DECLARATION_ENABLED	Publish the permission set at startup.	false	No
IDP_HOST	Access Manager base URL the set is published to. Must be https:// outside local and development environments.	—	With declaration
IDP_M2M_CLIENT_ID	Client ID of the service’s machine-to-machine application, whose name must be siloc.	—	With declaration
IDP_M2M_CLIENT_SECRET	Client secret of that application. Sensitive.	—	With declaration
PLUGIN_AUTH_ENABLED	Must be true so the service can obtain the token the publication uses. It does not control route authorization, which AUTH_ENABLED does.	—	With declaration
PLUGIN_AUTH_HOST	Access Manager address for that token.	—	With declaration

Observability

Variable	Description	Default	Required
ENABLE_TELEMETRY	Enable OpenTelemetry instrumentation.	false	No
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint.	—	If telemetry enabled
STREAMING_BROKERS	Broker addresses for the mandatory SILOC fact dispatcher. Streaming has no disabled mode: missing or invalid broker configuration prevents startup rather than leaving facts as PENDING. Configure the shared STREAMING_* settings as described in Streaming and outbox.	—	Yes
STREAMING_CLOUDEVENTS_SOURCE	CloudEvents source identity. Must be exactly br-siloc. A different value, including leading or trailing whitespace, prevents startup; the service uses that identity to derive its broker topics and access-control scope.	—	Yes

Health and readiness

Lerian SILOC exposes GET /health (liveness), GET /readyz (readiness), and GET /version on the main HTTP port. The service boots and serves these probes even before its datastores and settlement connection are reachable. /readyz reports the health of each dependency. See Health and readiness for the probe contract.