Environment variables

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 at deploy time; never commit.	—	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

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. A value other than `true` or `false` refuses to start.	`false`	No
`OT_REPLAY_INTERVAL`	How often the OT replay runs.	`10s`	No
`STATUS_REPLAY_ENABLED`	Apply the parked `PAG0101` participant-status messages.	`false`	No
`STATUS_REPLAY_INTERVAL`	How often the status replay runs.	`10s`	No
`RECONCILE_ENABLED`	Reconcile OT cycles against their final ROC, and settle a cycle whose ROC matches its settled instruction.	`false`	No
`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. A failed start is logged and the service keeps running. Disabled, its readiness check reports `skipped`; running, the check does not gate readiness.	`false`	No
`CARD_COMMAND_CONSUMER_ENABLED`	Consume card commands from Lerian SLC and send them to Núclea. A value other than `true` or `false` refuses to start.	`false`	No
`CARD_ROUTE_TENANT_ID`	The one tenant whose card commands this installation accepts, or `single-tenant`.	—	With card commands

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. Copy it exactly from the current Lerian deployment package. 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.

​Runtime and server

​Authentication

​PostgreSQL

​Redis

​SILOC settlement connectivity

​Outbound messages

​Message validation

​Certificates

​Trust and custody

​Background processing

​Permission declaration

​Observability

​Health and readiness