Environment variables

Lerian SPB is Lerian’s native messaging integration for the STR (Sistema de Transferência de Reservas), reaching BACEN’s real-time gross settlement system over the RSFN. The variables below are set at deploy time and require a service restart to take effect. Most of them are specific to this rail; for the knobs that behave the same way across every Lerian Go service — deployment posture, datastores, multi-tenancy, telemetry — see BYOC configuration essentials. In the tables below, Required marks a variable that must be set (globally, or under the condition named). A qualifier such as In production or If enabled narrows when the requirement applies. — means no default.

Lerian SPB arms its stricter security gates from ENV_NAME: when set to production or staging, TLS becomes mandatory on Redis, RabbitMQ, and the STR connection, message signing must use a hardware-backed custody backend, and development-only surfaces are rejected. ENV_NAME has no default — set it explicitly; the service refuses to start when it is unset or set to 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. Use `require` or stronger in production.	`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.	—	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
`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.	—	No
`STR_MQ_PASSWORD`	MQ connection password. Sensitive.	—	No
`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

STR messages are digitally signed. Choose a 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 dev/homologation only — rejected in production/staging. (`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.	—	No
`KEY_PATH`	Path to the signing private key (file backend only).	—	If `file`
`PROCESS_CERT_PATH`	Path to the process/TLS certificate.	—	No
`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.	—	No
`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.	—	If `kmip`
`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`	Publish attempts before an event is parked.	`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

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; it is backed by PostgreSQL, 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.	`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`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP collector endpoint.	`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

These variables expand the attack surface and are rejected or forced off in production/staging. Keep them unset outside local development.

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.	`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.

Overview

Lerian SPB

Lerian SPI

Lerian SILOC

Lerian SLC

Lerian STA

Lerian SISBAJUD

Lerian Consignado — Dataprev

Environment variables

Runtime and server

Authentication

PostgreSQL

PostgreSQL replica

Redis

STR connectivity (RSFN)

Circuit breaker

Message signing and certificates

PKCS#11 custody

KMIP custody

Events, outbox, and RabbitMQ

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

​Events, outbox, and RabbitMQ

​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

Events, outbox, and RabbitMQ

Approval (maker-checker)

Rate limiting and idempotency

Systemplane and runtime configuration

Encryption and secrets

Observability

Development-only

Health and readiness