> ## 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), 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](/en/reference/byoc-configuration).

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.

<Note>
  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.
</Note>

## 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. 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](/en/reference/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.                                  | `false` | No                    |

<Warning>
  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.
</Warning>

## 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

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

| 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](/en/reference/health-and-readiness) for the probe contract.