> ## 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.
# 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](/en/reference/byoc-configuration).
Lerian SILOC is an early-stage service. This page documents the current verified configuration surface. Expect it to grow as the rail matures. For example, Lerian plans a systemplane runtime-configuration plane but does not yet expose it. Treat the service's own environment reference as the source of truth for a given release.
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` arms the stricter authentication and TLS gates below. | `development` | No |
| `DEPLOYMENT_MODE` | TLS-enforcement posture (`local`, `byoc`, `saas`). `saas` makes TLS mandatory and refuses to start without it. See [Deployment mode and TLS](/en/reference/byoc-configuration#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 |
## Authentication
Lerian SILOC authorizes protected routes through Access Manager. It runs default-closed: authentication stays on unless you disable it.
| Variable | Description | Default | Required |
| -------------- | ------------------------------------------------------------------------------------------------- | ------- | ------------- |
| `AUTH_ENABLED` | Require Access Manager authentication on protected routes. Must be `true` in production and SaaS. | `true` | In production |
| `AUTH_ADDRESS` | Access Manager service address. Must be a valid `https://` URL in production and SaaS. | — | In production |
## 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. Use `require` or stronger in production. | `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. | — | No |
| `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. | `false` | 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. `MQ_PORT`, `MQ_TLS_ENABLED`, and `MQ_SSL_KEY_REPOSITORY` alone do not activate that validation.
| Variable | Description | Default | Required |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------- |
| `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..1`, where `` 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_TLS_ENABLED` | Enable mutual TLS on the MQ channel. Must be `true` in production. | `false` | In production |
| `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 |
## Certificates
| Variable | Description | Default | Required |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
| `CERT_READINESS_MIN_DAYS` | Days-to-expiry threshold that logs a warning for a currently valid certificate. 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. | — | No |
| `SFN_CUSTODY_CONFIG_PATH` | Path to the custody-provider configuration. | — | No |
| `SFN_CUSTODY_CACHE_ENTRIES` | Maximum number of custody entries kept in the in-memory cache. | `16` | No |
## 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](/en/reference/byoc-configuration#streaming-and-outbox). | — | Yes |
| `LDL_FACT_CONSUMER_ENABLED` | Enable the consumer of the authoritative SPB LDL settlement facts. Each fact completes the SILOC instruction it authorizes. With `true`, `STREAMING_BROKERS` and the PostgreSQL datastore are required, and the service refuses to start without them. Disabled, its readiness check reports `skipped`; running, the check does not gate readiness. | `false` | No |
## 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](/en/reference/health-and-readiness) for the probe contract.