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

# Operating Lerian SRC

> Readiness checks, the IBM MQ connection, credentials and keys, personal data, operator cases, runtime configuration, storage, metrics, and the deployment posture of Lerian SRC.

Lerian SRC carries your institution's consultations to BACEN. An instance that is not ready is an operational event.

## Health and readiness

***

`GET /health` reports liveness. `GET /readyz` runs the checks below. It answers `503` when a check reports `down` or `degraded`, and while the service shuts down.

| Check | What it probes |
| - | - |
| `postgres` | The PostgreSQL database. |
| `outbox_dispatcher` | The loop that publishes events from the outbox. It reports `skipped` while event publication is held, for example with no broker. |
| `src_mq` | The IBM MQ connection that carries consultations. |
| `custody` | The PKCS#11 or KMIP provider. |
| `trust_anchor` | BACEN's certificate. |
| `license` | The Lerian license server. |
| `runtime_config` | The runtime configuration store. |
| `declaration` | The permission declaration to Access Manager. It reports `skipped` while `IDP_DECLARATION_ENABLED` is `false`. |
| `startup_self_probe` | The startup self-check of the service. |

`GET /version` returns the build version of the service.

## IBM MQ

***

Lerian SRC connects to your institution's own IBM MQ queue manager. That queue manager reaches BACEN over the RSFN.

Set `SRC_MQ_HOST`, `SRC_MQ_PORT`, `SRC_MQ_CHANNEL`, and `SRC_MQ_QUEUE_MANAGER`. Lerian SRC applies no default for the port and the channel, so ask your IBM MQ team for them.

Lerian SRC derives the queue names from `SRC_CNPJ_BASE8`:

* Send queue: `QR.REQ.<CNPJ base>.00038166.03`.
* Receive queue: `QL.RSP.00038166.<CNPJ base>.03`.

Set `SRC_MQ_SEND_QUEUE` and `SRC_MQ_RECEIVE_QUEUE` only when your queue manager uses other names.

While `SRC_MQ_BACKOUT_THRESHOLD` is above `0`, a message that fails delivery that many times moves to the backout queue. The default threshold is 5. The backout queue is the receive queue name followed by `.BACKOUT`, unless you set `SRC_MQ_BACKOUT_QUEUE`. Lerian SRC opens the backout queue when it connects, so create it on the queue manager before you start the service.

When no IBM MQ call completes for `SRC_MQ_STALE_AFTER`, 30 seconds by default, the `src_mq` check reports `degraded`.

The Lerian SRC image runs on `linux/amd64`.

## Credentials and keys

***

Lerian SRC signs each message it sends to BACEN with your institution's private key. It uses BACEN's certificate to protect each message for BACEN.

Lerian SRC uses the private key through PKCS#11 or KMIP. When you configure both, it uses PKCS#11. Set `SRC_LOCAL_CERT_FILE` to your institution's certificate for that key, and `SRC_BACEN_CERT_FILE` to BACEN's certificate. After you replace BACEN's certificate, restart Lerian SRC.

`GET /v1/src/credentials` returns the status of the credential.

## Personal data

***

Lists, search results, and events show the person's document masked, in `documentMasked`. The evidence trail returns the full record, including the document. Lerian SRC records each read of the evidence trail in the same transaction as the read. If it cannot record the read, the read fails.

## Operator cases

***

`GET /v1/src/operator/cases` lists the open cases, newest first. Send `status=closed` for the closed cases, or `status=all` for both. [How Lerian SRC works](/en/rails/src/how-src-works#operator-cases) explains the legs.

Close a case with the operation of its leg:

| Leg | Operation |
| - | - |
| `orphan_response` | `POST /v1/src/operator/orphan-responses/{caseId}/closure` |
| `invalid_outbound` | `POST /v1/src/operator/invalid-dispatches/{caseId}/closure` |

A `budget_exhausted` case has `closable` set to `false`. A closure of a case that is not open returns `404` with code `SRC-0301`.

Watch two numbers on `GET /v1/src/dashboard/consultations`:

* `openOperatorCases`: the operator cases that are open now.
* `pendingBeyondExpected`: the consultations that stay `pending` longer than `src.pending.alert_threshold`, 15 minutes by default.

## Runtime configuration (Systemplane)

***

Lerian SRC serves its runtime configuration admin API at `/v1/system`. [Authentication and permissions](/en/rails/src/src-integration#authentication-and-permissions) names the permission it needs. The admin API accepts 30 requests per minute from each client IP address.

A change takes effect without a restart. The tables list the keys that tune consultations, retries, rate limits, and retention. See [System plane](/en/reference/platform/systemplane/overview).

**Namespace `tenant_policy`**

| Key | What it controls | Default | Range |
| - | - | - | - |
| `src.channel.active` | The channel that carries consultations to BACEN. | `messaging` | `messaging` |
| `src.consultation.protection_types` | The protection types that a consultation can carry. A request with another type returns `422`. | `account_opening,ownership_change` | `account_opening`, `ownership_change` |
| `src.pending.alert_threshold` | How long a consultation can stay `pending` before `pendingBeyondExpected` counts it. | `15m` | `1m` to `168h` |

**Namespace `runtime_config`**

| Key | What it controls | Default | Range |
| - | - | - | - |
| `src.dispatch.max_attempts` | Attempts for each consultation. | `8` | 1 to 20 |
| `src.dispatch.backoff_initial` | Wait before the first retry. | `1m` | `1s` to `1h` |
| `src.dispatch.backoff_ceiling` | Longest wait between two attempts. | `30m` | `1m` to `24h` |
| `src.log.level` | Log level. | `INFO` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `src.rate_limit.ip_max` | Requests that one client IP address can send in each window, in each replica. | `6000` | 1 to 1000000 |
| `src.rate_limit.ip_window` | Length of the rate-limit window. | `1m` | `1s` to `1h` |
| `src.retention.transient_purge_age` | Age after which the sweep can delete an idempotency key. | `24h` | `1h` to `720h` |
| `src.retention.transient_purge_batch` | Idempotency keys that one purge statement deletes. | `1000` | 100 to 10000 |
| `src.retention.resolved_orphan_payload_purge_age` | How long a closed orphan-response case keeps the message that Lerian SRC received. | `8760h` | `24h` to `8760h` |

## Storage, outbox and retention

***

Lerian SRC stores its state in PostgreSQL.

Events leave through an outbox table, in the same transaction as the change they report. With no broker, the events stay pending in the outbox.

The retention sweep deletes idempotency keys older than `src.retention.transient_purge_age`, 24 hours by default.

Lerian SRC does not apply its own database schema. The `br-src-migrations` image applies it. Run that image before you start the `br-src` image.

## Metrics and tracing

***

Set `ENABLE_TELEMETRY=true` to export traces and metrics over OTLP to `OTEL_EXPORTER_OTLP_ENDPOINT`. Lerian SRC has no `/metrics` endpoint. See [Observability](/en/platform/observability) for the platform view.

## Deployment posture

***

`DEPLOYMENT_MODE` takes `local`, `byoc`, or `saas`. One deployment serves one institution.

[Environment variables](/en/rails/src/src-environment-variables) defines a production deployment and marks each setting that it requires. A missing required setting stops the boot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.