Environment variables

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, and telemetry), see BYOC configuration essentials. 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 and the STR connection, and verify-full on PostgreSQL. It also requires hardware-backed custody for the key that decrypts inbound messages, 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
`DEPLOYMENT_MODE`	Deployment flavor: `local`, `byoc`, or `saas`. Production and staging refuse to start without it. `saas` also requires `ENV_NAME` `production` or `staging`, TLS on the datastores, upstreams, and broker, and SASL on the broker.	`local`	In production/staging
`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.

Variable	Description	Default	Required
`PLUGIN_AUTH_ENABLED`	Require Access Manager authentication on protected routes. Set it to `true` or `false`; the service refuses to start when it is unset. `false` is accepted only with `ENV_NAME=develop` and a `DEPLOYMENT_MODE` other than `saas`.	—	Yes
`PLUGIN_AUTH_ADDRESS`	Access Manager service address. Must be an `https://` URL in production/staging.	`http://localhost:4000`	In production/staging

PostgreSQL

Variable	Description	Default	Required
`POSTGRES_HOST`	Primary PostgreSQL host. Must not be `localhost` in production/staging.	`localhost`	In production/staging
`POSTGRES_PORT`	Primary PostgreSQL port.	`5432`	No
`POSTGRES_USER`	Database user.	`postgres`	No
`POSTGRES_PASSWORD`	Database password. Sensitive. Inject it at deploy time and never commit it. Must not be `postgres` in production/staging.	`postgres`	In production/staging
`POSTGRES_DB`	Database name.	Service default	No
`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.	—	In production/staging
`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. The three queue names derive from STR_ISPB. Production and staging refuse a queue name that differs from the derived name.

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 8-digit câmara ISPB other than `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 stem of the GSKit key repository backing MQ TLS. The private key lives here, never in an environment variable.	—	In production/staging
`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 that the service sets on the channel (Go duration).	`300s`	No
`MQ_DISCONNECT_INTERVAL`	Disconnect interval expected on the queue manager (Go duration). The service logs it at connect and does not set it.	`6000s`	No
`MQ_SEQ_WRAP`	Message-sequence wrap ceiling expected on the queue-manager channel. The service logs it and does not set it.	`99999999`	No
`MQ_ADOPTNEWMCA`	`AdoptNewMCA` setting expected on the queue manager. The service logs it and does not set it.	`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 failure ratio can trip the breaker.	`10`	No

Message signing and certificates

Lerian SPB signs every outbound STR message with the certificate at CERT_PATH and its key at KEY_PATH. The signing identity’s metadata file under CERT_BASE_PATH can move that key to a PKCS#11 or KMIP HSM. SPB_SIGNER_KIND chooses the custody backend of a different key: the key that decrypts inbound messages. Production and staging reject the file backend for that key and require pkcs11 or kmip.

Variable	Description	Default	Required
`SPB_SIGNER_KIND`	Custody backend of the inbound-decryption key: `file`, `pkcs11`, or `kmip`. `file` is permitted only when `ENV_NAME=develop`; production and staging reject it. The service refuses `hsm` and `kms`.	`file`	No
`CERT_BASE_PATH`	Base directory for the signing identity’s certificate material and metadata file.	`/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 certificate of the inbound-decryption key.	—	In production/staging
`PROCESS_PRIVATE_KEY_PATH`	Path to the inbound-decryption private key when `SPB_SIGNER_KIND=file`. 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. `/readyz` fails a certificate that expires sooner.	`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. Unset, the service uses `SPB_KMIP_SIGN_PRIVATE_KEY_UID`.	—	No
`SPB_KMIP_DIGEST_INFO_PREFIX`	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	`false`	No

Signing identity metadata file

Lerian SPB reads an optional metadata.json file directly under CERT_BASE_PATH. Without this file, the service reads the signing key from KEY_PATH. The signerKind field sets where the signing key is kept:

file or no value: the key file at KEY_PATH.
pkcs11: a key on a PKCS#11 token, set in the pkcs11 block.
kmip: a key in a KMIP network HSM, set in the kmip block.

With pkcs11 or kmip, the signing key stays in the HSM, and the signer reads only the certificate from CERT_PATH. The public key of the certificate must match the HSM key. Production and staging still require KEY_PATH to be set. The service rejects other signerKind values. It also rejects pkcs11 or kmip without the matching block.

{
  "signerKind": "pkcs11",
  "pkcs11": {
    "modulePath": "/usr/lib/pkcs11/module.so",
    "tokenLabel": "spb",
    "pinFile": "/certs/token.pin",
    "keyLabel": "spb-signing"
  }
}

Block	Field	Description	Required
`pkcs11`	`modulePath`	Path to the PKCS#11 module library.	Yes
`pkcs11`	`tokenLabel`	PKCS#11 token label.	Yes
`pkcs11`	`pinFile`	Path to a file holding the token PIN. Sensitive.	Yes
`pkcs11`	`keyLabel`	Label of the signing key on the token.	Yes
`kmip`	`baseUrl`	KMIP service base URL.	Yes
`kmip`	`vhsm`	Virtual HSM identifier.	Yes
`kmip`	`cryptoUser`	KMIP crypto user.	Yes
`kmip`	`cryptoUserToken`	KMIP crypto-user token. Sensitive.	Yes
`kmip`	`signPrivateKeyUid`	UID of the signing private key.	Yes
`kmip`	`signPublicKeyUid`	UID of the signing public key.	Yes
`kmip`	`digestInfoPrefix`	Boolean. Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. Default `false`.	No

Events and outbox

Lerian SPB records every message before dispatch and publishes lifecycle events through a transactional outbox to the streaming broker. Streaming has no disabled mode. Configure the shared STREAMING_* settings as described in Streaming and outbox.

Variable	Description	Default	Required
`STREAMING_BROKERS`	Broker addresses for event publication. The service refuses to start when the value is absent or invalid.	—	Yes
`STREAMING_CLOUDEVENTS_SOURCE`	CloudEvents source identity. Must be exactly `br-spb`. A different value prevents startup; the service derives its broker topics from it.	—	Yes
`EMISSION_REQUIRED`	When `true`, bootstrap fails closed unless event emission is fully wired.	`false`	No
`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`	Total dispatch attempts for an outbox row, across dispatch cycles, before the service stops retrying it. 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`	Webhook delivery attempts before the delivery is marked `EXHAUSTED`.	`3`	No
`EVENT_DELIVERY_RETRY_BACKOFF`	Delay between webhook 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). 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`	Initial band table: semicolon-separated `maxExclusive:requiredSignatures` bands (e.g. `10000.00:1;100000.00:2`). Empty keeps approval off until an operator sets bands through the governance API.	—	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. Production and staging refuse `false`.	`true`	No
`IDEMPOTENCY_DEFAULT_TTL_SEC`	How long (seconds) an idempotency key is retained.	`86400`	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 for the API, namespaces, and permissions. The CORS origins, the four rate-limit values, the three outbox dispatch values, and the approval bands are hot-reloadable. For these settings, the variable sets the initial value, and a value stored in Systemplane takes precedence.

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, as 64 hexadecimal characters. Sensitive. Required in production/staging.	—	In production/staging
`INBOUND_ALLOW_CLEARTEXT_FALLBACK`	Allow the inbound path to accept unencrypted payloads. Production and staging refuse `true`.	`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
`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`	Let the service start in `develop` without BACEN’s public certificate and the inbound-decryption key. Refused outside `develop` and with a real `STR_MQ_HOST`.	`false`	No

Health and readiness

Lerian SPB exposes GET /health (liveness) and GET /readyz (readiness) on the main HTTP port. See Health and readiness for the probe contract.

​Runtime and server

​Authentication

​PostgreSQL

​PostgreSQL replica

​Redis

​STR connectivity (RSFN)

​Circuit breaker

​Message signing and certificates

​PKCS#11 custody

​KMIP custody

​Signing identity metadata file

​Events and outbox

​Approval (maker-checker)

​Rate limiting and idempotency

​Systemplane and runtime configuration

​Encryption and secrets

​Observability

​Development-only

​Health and readiness

Runtime and server

Authentication

PostgreSQL

PostgreSQL replica

Redis

STR connectivity (RSFN)

Circuit breaker

Message signing and certificates

PKCS#11 custody

KMIP custody

Signing identity metadata file

Events and outbox

Approval (maker-checker)

Rate limiting and idempotency

Systemplane and runtime configuration

Encryption and secrets

Observability

Development-only

Health and readiness