> ## 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 SPB: runtime, STR/RSFN connectivity, message signing and certificates, persistence, events, and security.
Lerian SPB is Lerian's native messaging integration for the STR (Sistema de Transferência de Reservas), BACEN's real-time gross settlement system, reached over the RSFN. Set these variables at deploy time. A change takes effect only after you restart the service. Most variables are specific to this rail. For the knobs that behave the same way across every Lerian Go service (deployment posture, datastores, multi-tenancy, and telemetry), see [BYOC configuration essentials](/en/reference/byoc-configuration).
In the tables below, **Required** marks a variable you must set, globally or under the condition named. A qualifier such as *In production* or *If enabled* narrows when the requirement applies. `—` means no default.
`ENV_NAME` arms the stricter security gates. Set it to `production` or `staging` and the service enforces TLS on Redis, RabbitMQ, and the STR connection. It also requires a hardware-backed signing custody backend and rejects development-only surfaces. `ENV_NAME` has no default. Set it explicitly. The service refuses to start when `ENV_NAME` is unset or holds an unrecognized value.
## Runtime and server
| Variable | Description | Default | Required |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------- |
| `ENV_NAME` | Runtime environment. Must be one of `production`, `staging`, or `develop`. Production and staging arm the security gates described above. | — | Yes |
| `SERVICE_NAME` | Service identifier used in logs and telemetry. | Service default | No |
| `LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_PORT` | HTTP listen port. The liveness, readiness, and systemplane surfaces bind this same port. | `3000` | No |
| `CORS_ALLOWED_ORIGINS` | Comma-separated allowed CORS origins. In production/staging, only `https://` origins are accepted and localhost origins are rejected. | `http://localhost:3000` | No |
| `TRUSTED_PROXIES` | Comma-separated proxy IPs/CIDRs trusted to set the real client IP. | — | No |
## Authentication
Lerian SPB delegates authorization, including the systemplane admin API, to Access Manager. See [BYOC configuration essentials](/en/reference/byoc-configuration#plugin-authentication).
| Variable | Description | Default | Required |
| --------------------- | ---------------------------------------------------------- | ----------------------- | ---------- |
| `PLUGIN_AUTH_ENABLED` | Require Access Manager authentication on protected routes. | `true` | No |
| `PLUGIN_AUTH_ADDRESS` | Access Manager service address. | `http://localhost:4000` | If enabled |
## PostgreSQL
| Variable | Description | Default | Required |
| ----------------------------- | ------------------------------------------------------------------- | ----------- | --------------------- |
| `POSTGRES_HOST` | Primary PostgreSQL host. | `localhost` | Yes |
| `POSTGRES_PORT` | Primary PostgreSQL port. | `5432` | No |
| `POSTGRES_USER` | Database user. | — | Yes |
| `POSTGRES_PASSWORD` | Database password. Sensitive — inject at deploy time; never commit. | — | In production/staging |
| `POSTGRES_DB` | Database name. | — | Yes |
| `POSTGRES_SSLMODE` | libpq TLS mode. Must be `verify-full` in production/staging. | `require` | No |
| `POSTGRES_MAX_OPEN_CONNS` | Maximum open connections. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Maximum idle connections. | `10` | No |
| `POSTGRES_CONN_MAX_LIFETIME` | Connection max lifetime (Go duration, e.g. `5m`). | `5m` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME` | Connection max idle time (Go duration). | `2m` | No |
### PostgreSQL replica
Optional read replica. All fields fall back to the primary when unset.
| Variable | Description | Default | Required |
| --------------------------- | ------------------------------------------------------------------------------------ | ------- | -------- |
| `POSTGRES_REPLICA_HOST` | Replica host. Unset = no replica. | — | No |
| `POSTGRES_REPLICA_PORT` | Replica port. | — | No |
| `POSTGRES_REPLICA_USER` | Replica user. | — | No |
| `POSTGRES_REPLICA_PASSWORD` | Replica password. Sensitive. | — | No |
| `POSTGRES_REPLICA_DB` | Replica database name. | — | No |
| `POSTGRES_REPLICA_SSLMODE` | Replica TLS mode. Must be `verify-full` in production/staging when a replica is set. | — | No |
## Redis
| Variable | Description | Default | Required |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------- | --------------------- |
| `REDIS_HOST` | Redis host. Must be explicit and non-local in production/staging. | `localhost` | In production/staging |
| `REDIS_PORT` | Redis port. | `6379` | No |
| `REDIS_PASSWORD` | Redis password. Sensitive. | — | In production/staging |
| `REDIS_DB` | Redis database number. | `0` | No |
| `REDIS_TLS_ENABLED` | Enable TLS to Redis. Must be `true` in production/staging. | `false` | In production/staging |
| `REDIS_TLS_CA_CERT_BASE64` | Base64-encoded CA certificate for Redis TLS. Required when `REDIS_TLS_ENABLED=true` in production/staging. | — | If TLS enabled |
| `REDIS_POOL_SIZE` | Connection pool size. | `20` | No |
| `REDIS_MIN_IDLE_CONNS` | Minimum idle connections. | `5` | No |
## STR connectivity (RSFN)
Lerian SPB exchanges STR messages with BACEN over the RSFN using an IBM MQ transport. These variables define the participant identity, the queue-manager connection, and the queues.
| Variable | Description | Default | Required |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------- |
| `STR_ISPB` | The participant's 8-digit ISPB. In production/staging it must be an explicit real ISPB, not `00000000`. | `00000000` | In production/staging |
| `SILOC_ISPB` | The SILOC câmara's 8-digit ISPB, resolved server-side into SILOC-related settlement messages — never client-supplied. In production/staging it must be an explicit 8-digit câmara ISPB, not `00000000`. | `02992335` | No |
| `STR_MQ_HOST` | Queue-manager host. | — | Yes (live STR) |
| `STR_MQ_PORT` | Queue-manager listener port. | `1414` | No |
| `STR_MQ_CHANNEL` | MQ server-connection channel. | `DEV.APP.SVRCONN` | No |
| `STR_MQ_QUEUE_MGR` | Queue-manager name. | `QM1` | No |
| `STR_MQ_USER` | MQ connection user. | `app` | No |
| `STR_MQ_PASSWORD` | MQ connection password. Sensitive. | — | In production/staging |
| `STR_MQ_TLS_ENABLED` | Enable mutual TLS on the MQ channel. Required for a real STR connection. | `false` | In production/staging |
| `MQSSLKEYR` | Path to the GSKit key repository backing MQ TLS. The private key lives here, never in an environment variable. | — | If TLS enabled |
| `STR_MQ_SEND_QUEUE` | Outbound request queue. Derived from `STR_ISPB` when unset. | Derived | No |
| `STR_MQ_RESPONSE_QUEUE` | Response queue. Derived from `STR_ISPB` when unset. | Derived | No |
| `STR_MQ_RECEIVE_QUEUE` | Inbound receive queue. Derived from `STR_ISPB` when unset. | Derived | No |
| `MQ_HEARTBEAT_INTERVAL` | MQ heartbeat interval (Go duration). | `300s` | No |
| `MQ_DISCONNECT_INTERVAL` | MQ disconnect interval (Go duration). | `6000s` | No |
| `MQ_SEQ_WRAP` | Message-sequence wrap ceiling for the MQ channel. | `99999999` | No |
| `MQ_ADOPTNEWMCA` | MQ `AdoptNewMCA` channel setting. | `ALL` | No |
### Circuit breaker
Guards the STR transport against a failing queue manager.
| Variable | Description | Default | Required |
| ------------------------- | ------------------------------------------------------------- | ------- | -------- |
| `CB_MAX_REQUESTS` | Requests allowed through while the breaker is half-open. | `3` | No |
| `CB_INTERVAL` | Rolling window over which failures are counted (Go duration). | `30s` | No |
| `CB_TIMEOUT` | Open-state recovery timeout (Go duration). | `10s` | No |
| `CB_CONSECUTIVE_FAILURES` | Consecutive failures before the breaker trips. | `5` | No |
| `CB_FAILURE_RATIO` | Failure ratio that trips the breaker (0–1). | `0.5` | No |
| `CB_MIN_REQUESTS` | Minimum requests in a window before the breaker can trip. | `10` | No |
## Message signing and certificates
Lerian SPB signs every STR message. Choose the key-custody backend with `SPB_SIGNER_KIND`. Production and staging reject the `file` backend and require a hardware-backed key (`pkcs11` or `kmip`).
| Variable | Description | Default | Required |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------- |
| `SPB_SIGNER_KIND` | Signing custody backend: `file`, `pkcs11`, or `kmip`. `file` is permitted only when `ENV_NAME=develop`; production and staging reject it. (`hsm` and `kms` are declared but not implemented.) | `file` | No |
| `CERT_BASE_PATH` | Base directory for certificate material. | `/certs` | No |
| `CERT_PATH` | Path to the signing certificate. | — | In production/staging |
| `KEY_PATH` | Path to the signing private key. | — | In production/staging |
| `PROCESS_CERT_PATH` | Path to the process/TLS certificate. | — | In production/staging |
| `PROCESS_PRIVATE_KEY_PATH` | Path to the process/TLS private key. Sensitive. | — | No |
| `BACEN_PUBLIC_CERT_PATH` | Path to BACEN's public certificate, used to verify inbound signatures and for SFN encryption. | — | In production/staging |
| `CERT_READINESS_MIN_DAYS` | Minimum days-to-expiry before the certificate readiness check reports degraded. | `30` | No |
### PKCS#11 custody
Required when `SPB_SIGNER_KIND=pkcs11`.
| Variable | Description | Default | Required |
| ------------------------ | ------------------------------------------------ | ------- | ----------- |
| `SPB_PKCS11_MODULE_PATH` | Path to the PKCS#11 module library. | — | If `pkcs11` |
| `SPB_PKCS11_TOKEN_LABEL` | PKCS#11 token label. | — | If `pkcs11` |
| `SPB_PKCS11_PIN_FILE` | Path to a file holding the token PIN. Sensitive. | — | If `pkcs11` |
| `SPB_PKCS11_KEY_LABEL` | Label of the signing key on the token. | — | If `pkcs11` |
### KMIP custody
Required when `SPB_SIGNER_KIND=kmip` (KMIP-over-HTTP to a network HSM).
| Variable | Description | Default | Required |
| ------------------------------- | -------------------------------------------------------------- | ------- | --------- |
| `SPB_KMIP_BASE_URL` | KMIP service base URL. | — | If `kmip` |
| `SPB_KMIP_VHSM` | Virtual HSM identifier. | — | If `kmip` |
| `SPB_KMIP_CRYPTO_USER` | KMIP crypto user. | — | If `kmip` |
| `SPB_KMIP_CRYPTO_USER_TOKEN` | KMIP crypto-user token. Sensitive. | — | If `kmip` |
| `SPB_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key. | — | If `kmip` |
| `SPB_KMIP_SIGN_PUBLIC_KEY_UID` | UID of the signing public key. | — | If `kmip` |
| `SPB_KMIP_DECRYPT_KEY_UID` | UID of the decryption key used on the inbound decrypt path. | — | No |
| `SPB_KMIP_DIGEST_INFO_PREFIX` | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. | `false` | No |
## Events, outbox, and RabbitMQ
Lerian SPB records every message before dispatch and publishes lifecycle events through a transactional outbox to RabbitMQ.
| Variable | Description | Default | Required |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------- |
| `EMISSION_REQUIRED` | When `true`, bootstrap fails closed unless event emission is fully wired. | `false` | No |
| `RABBITMQ_HOST` | RabbitMQ host. | — | Yes (events) |
| `RABBITMQ_PORT` | RabbitMQ port. | `5672` | No |
| `RABBITMQ_USER` | RabbitMQ user. Must not be the default `guest` in production/staging. | `guest` | In production/staging |
| `RABBITMQ_PASSWORD` | RabbitMQ password. Sensitive. Must not be empty or default in production/staging. | `guest` | In production/staging |
| `RABBITMQ_VHOST` | RabbitMQ virtual host. | `/` | No |
| `RABBITMQ_STR_EXCHANGE` | Exchange name for STR lifecycle events. | `str.events` | No |
| `RABBITMQ_TLS_ENABLED` | Enable TLS to RabbitMQ. Must be `true` in production/staging when a host is set. | `false` | In production/staging |
| `OUTBOX_DISPATCH_INTERVAL` | Interval between outbox dispatch cycles (Go duration). | `2s` | No |
| `OUTBOX_BATCH_SIZE` | Rows drained per dispatch cycle. | `50` | No |
| `OUTBOX_MAX_PUBLISH_ATTEMPTS` | Maximum RabbitMQ publisher retry attempts for each publish call. Webhook delivery exhaustion is governed separately by `EVENT_DELIVERY_MAX_ATTEMPTS`. | `3` | No |
| `OUTBOX_POSTGRES_MAX_OPEN_CONNS` | Max open connections for the outbox pool. | `10` | No |
| `OUTBOX_POSTGRES_MAX_IDLE_CONNS` | Max idle connections for the outbox pool. | `5` | No |
| `EVENT_DELIVERY_BATCH_SIZE` | Events delivered per cycle. | `25` | No |
| `EVENT_DELIVERY_MAX_ATTEMPTS` | Delivery attempts before an event is parked. | `3` | No |
| `EVENT_DELIVERY_RETRY_BACKOFF` | Base backoff between delivery retries (Go duration). | `30s` | No |
| `DISPATCH_MAX_AUTO_ATTEMPTS` | Automatic dispatch attempts before manual intervention. | `8` | No |
| `DISPATCH_RETRY_BACKOFF_CEILING` | Maximum backoff between dispatch retries (Go duration). | `30m` | No |
| `LDL_ADVISORY_CONSUMER_ENABLED` | Enable the supervised consumer of SILOC OT-settlement advisory facts. It requires `STREAMING_BROKERS` and durable persistence when enabled, and refuses to start without them. The consumer topic and group are fixed in the service; neither is configurable through the environment. The broker connection comes from the shared `STREAMING_*` settings (see [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox)). Disabled, its readiness check reports `skipped`. | `false` | No |
## Approval (maker-checker)
Optional value-band approval that gates STR emission. Off by default. An empty band table lets every emission proceed single-step.
| Variable | Description | Default | Required |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `APPROVAL_ALCADA_BANDS` | Semicolon-separated `maxExclusive:requiredSignatures` bands (e.g. `10000.00:1;100000.00:2`). Empty keeps approval off. | — | No |
| `APPROVAL_DEADLINE_WINDOW` | How long a parked emission may wait (Go duration, capped at 7 days). | `24h` | No |
| `APPROVAL_EXPIRY_ENABLED` | Run the background sweep that expires overdue parked emissions. | `true` | No |
| `APPROVAL_EXPIRY_SWEEP_INTERVAL` | Sweep interval (Go duration). | `1m` | No |
## Rate limiting and idempotency
| Variable | Description | Default | Required |
| ----------------------------- | -------------------------------------------------- | ------- | -------- |
| `RATE_LIMIT_IP_MAX` | Max requests per IP per window. | `300` | No |
| `RATE_LIMIT_IP_WINDOW` | Per-IP rate-limit window (Go duration). | `1m` | No |
| `RATE_LIMIT_KEY_MAX` | Max requests per API key per window. | `100` | No |
| `RATE_LIMIT_KEY_WINDOW` | Per-key rate-limit window (Go duration). | `1m` | No |
| `IDEMPOTENCY_ENABLED` | Enable idempotency-key deduplication. | `true` | No |
| `IDEMPOTENCY_DEFAULT_TTL_SEC` | How long (seconds) an idempotency key is retained. | `300` | No |
## Systemplane and runtime configuration
Lerian SPB mounts the systemplane runtime-configuration admin API at `/v1/system` on the main port. PostgreSQL backs this plane, so operators can read and change hot-reloadable settings without a restart. See [Systemplane](/en/reference/platform/systemplane/overview) for the API, namespaces, and permissions.
| Variable | Description | Default | Required |
| ---------------------------- | --------------------------------------------------------------------------------------------------- | --------------- | -------- |
| `SYSTEMPLANE_LISTEN_CHANNEL` | PostgreSQL `LISTEN`/`NOTIFY` channel the runtime-config plane subscribes to for hot config changes. | Service default | No |
## Encryption and secrets
| Variable | Description | Default | Required |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------- | --------------------- |
| `STR_PAYLOAD_ENCRYPTION_KEY` | Base64-encoded AES-256 key for at-rest encryption of stored STR payloads. Sensitive. Required in production/staging. | — | In production/staging |
| `WEBHOOK_SECRET_KEY` | Key used to encrypt stored webhook secrets. Sensitive. Required in production/staging. | — | In production/staging |
| `INBOUND_ALLOW_CLEARTEXT_FALLBACK` | Allow the inbound path to accept unencrypted payloads. Leave `false` in production and staging. | `false` | No |
Never commit or log the values of any variable marked *Sensitive* (passwords, tokens, PINs, and AES keys). Inject them at deploy time through your secret manager.
## Observability
| Variable | Description | Default | Required |
| ----------------------------- | ---------------------------------------------------------------------- | ----------------------- | --------------------- |
| `ENABLE_TELEMETRY` | Enable OpenTelemetry tracing and metrics. | `false` | In production/staging |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint. Must use `https://` in production/staging. | `http://localhost:4318` | If telemetry enabled |
| `OTEL_RESOURCE_SERVICE_NAME` | Service name attached to exported telemetry. | Service default | No |
| `METRICS_PROMETHEUS_ENABLED` | Expose a dedicated Prometheus scrape endpoint. | `false` | No |
| `METRICS_PROMETHEUS_ADDRESS` | Listen address for the Prometheus endpoint. Binds loopback by default. | `127.0.0.1:9090` | No |
## Development-only
Keep these variables unset outside local development. They expand the attack surface, and production or staging rejects or forces them off.
| Variable | Description | Default | Required |
| --------------------------- | ----------------------------------------------------------------------------------- | ----------------------- | ---------------- |
| `ENABLE_DEV_DEBUG_ROUTES` | Expose debug routes. Forbidden in production/staging. | `false` | No |
| `DEV_DEBUG_TOKEN` | Token guarding the debug routes. Sensitive. Required when debug routes are enabled. | — | If debug enabled |
| `SWAGGER_ENABLED` | Serve the OpenAPI spec and API docs UI. Forced off in production and staging. | `false` | No |
| `STR_MQ_MOCK` | Route the STR transport to a mock instead of a live queue manager. | `false` | No |
| `STR_MQ_MOCK_HOST` | Mock STR host. Required when `STR_MQ_MOCK=true`. | `http://localhost:8080` | If mock enabled |
| `STR_MQ_MOCK_ALLOWED_HOSTS` | Allow-list of hosts the mock transport may reach. | — | No |
| `ALLOW_MOCK_TRANSPORT` | Permit the mock transport to be selected at all. | `false` | No |
## Health and readiness
Lerian SPB exposes `GET /health` (liveness) and `GET /readyz` (readiness) on the main HTTP port. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.