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.

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.

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). 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 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 for the probe contract.