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

> Environment variables for deploying and operating Pix Lerian: identity, databases, integrations, connectivity, and events.

Pix Lerian consists of the SPI, DICT, and COB domains and the connectivity adapter. The DevOps team configures its behavior through environment variables at deployment time. This page covers the variables **specific to this interface**. For shared server, telemetry, authentication, streaming, and service discovery parameters, see the [BYOC configuration reference](/en/reference/byoc-configuration).

<Note>
  In the tables below, the **Default / Required** column shows the default value. A bold qualifier marks a variable that you must set in the described context. `—` means there is no default. `🔒` marks a **secret** — inject it at deployment time from your secret store and never commit it.
</Note>

## How `values.yaml` and Systemplane work together

For initial deployment, customers provide configuration through the Helm chart `values.yaml` delivered with the release. After initialization, runtime keys are managed through Systemplane.

The chart turns values into pod environment variables:

| Type                     | Location in `values.yaml`                                | Behavior                                                                                                                          |
| ------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Deployment configuration | `<component>.configmap.<VARIABLE>`                       | Helm renders the configuration, and the Deployment injects the keys as environment variables.                                     |
| Secret                   | Component Secret configuration                           | Inject the value at deployment time from the secret store and never commit it.                                                    |
| Runtime seed             | `spiSystemplane`, `dictSystemplane`, or `cobSystemplane` | Set the variable in the Systemplane block that owns the domain. The component uses the value to initialize runtime configuration. |

Each domain has a dedicated Systemplane component. The flow is:

<Steps>
  <Step title="Render the release">
    Helm creates each component's ConfigMap and references its Secret. The Deployment loads both with `envFrom` when the pod starts.
  </Step>

  <Step title="Initialize runtime configuration">
    The Systemplane component reads mapped environment variables and applies a seed only while the stored value still equals the registered default. An existing administrative override is not overwritten.
  </Step>

  <Step title="Consume the configuration">
    Domain APIs and workers read the Systemplane store. Each key definition determines whether it supports runtime updates or requires a restart.
  </Step>

  <Step title="Change the correct source">
    For bootstrap variables, update `values.yaml`, run the upgrade, and roll out the component. After initialization, change runtime keys through Systemplane; changing `values.yaml` alone does not replace a stored override.
  </Step>
</Steps>

* **Direct bootstrap environment variables:** `APPLICATION_NAME`, `SERVER_ADDRESS`, `DATABASE_URL`, `SYSTEMPLANE_POSTGRES_DSN`, `SYSTEMPLANE_SECRET_MASTER_KEY`, `VALKEY_URL`, `LICENSE_KEY`, `ORGANIZATION_IDS`, `SWAGGER_ENABLED`, `RABBITMQ_ENABLED`, `RABBITMQ_URI`, and `STREAMING_*`.
* **Also used as Systemplane seeds:** `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC`, `PLUGIN_AUTH_*`, `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*`, `COB_*`, `SPI_*`, `KEY_CACHE_TTL_SEC`, and `VSYNC_*`.

<Note>
  Set seeds in the Systemplane block that owns the domain, not in the API or worker block. Sensitive keys remain marked with `🔒` in the tables below.
</Note>

| Chart block       | Domain-specific seeds                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `spiSystemplane`  | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*`, and `COB_*`.                                        |
| `dictSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `CRM_*`, `SPI_*`, `KEY_CACHE_TTL_SEC`, and `VSYNC_*`.                             |
| `cobSystemplane`  | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET`, and `DICT_ROUTING_MODE`. |

All three blocks also receive the shared `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC`, and `PLUGIN_AUTH_*` seeds.

Pix Lerian does not expose catalog discovery. Use this page as the supported-key reference, and see [Systemplane](/en/reference/systemplane/overview) for the authorization and runtime update model.

## Server and deployment mode

Each component receives `SERVER_ADDRESS` from `<component>.configmap.SERVER_ADDRESS`; the value must match `<component>.service.port` in the same `values.yaml`. Liveness and readiness probes use that port. See [Server](/en/reference/byoc-configuration#server) and [Health and readiness](/en/reference/health-and-readiness).

| Variable              | Default / Required                      | Description                                                                                                                                   |
| --------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLICATION_NAME`    | Defined by the chart                    | Component identity used for licensing, logs, and telemetry. Do not override the value supplied by the chart.                                  |
| `SERVER_ADDRESS`      | Defined by the chart                    | HTTP listen address in `host:port` format; it must match the component `targetPort`.                                                          |
| `DEPLOYMENT_MODE`     | `byoc`                                  | Deployment mode delivered to customers. Keep the value defined by the chart.                                                                  |
| `REQUEST_TIMEOUT_SEC` | `30`                                    | Default HTTP request timeout, in seconds.                                                                                                     |
| `PLUGIN_AUTH_ENABLED` | `false`                                 | Requires Access Manager authentication on protected routes. Enable it in production.                                                          |
| `PLUGIN_AUTH_URL`     | **Required with authentication or M2M** | Access Manager base URL used for inbound authentication and OAuth clients between components.                                                 |
| `LICENSE_KEY`         | 🔒 **Required in BYOC**                 | Pix Lerian license key.                                                                                                                       |
| `ORGANIZATION_IDS`    | **Required when `LICENSE_KEY` is set**  | License scope: `global` or a comma-separated organization list. Use this exact name; current binaries do not read `LICENSE_ORGANIZATION_IDS`. |
| `SWAGGER_ENABLED`     | Enabled outside production              | Controls the OpenAPI specification and exploration interface served by the component.                                                         |

## Persistence and runtime configuration

SPI, DICT, COB, and the adapter maintain separate stores. Do not reuse the same logical database across domains.

| Variable                        | Default / Required                              | Description                                                                                                            |
| ------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`                  | 🔒 **Required for components with persistence** | Component PostgreSQL DSN used by services that persist business data and by configuration components.                  |
| `SYSTEMPLANE_POSTGRES_DSN`      | 🔒 `DATABASE_URL` in SPI, DICT, and COB         | Dedicated DSN for reading runtime configuration. Use the value rendered by the component chart.                        |
| `SYSTEMPLANE_SECRET_MASTER_KEY` | 🔒 **Required in BYOC**                         | 32-byte AES-256-GCM key used to encrypt secret values in the configuration store.                                      |
| `VALKEY_URL`                    | 🔒 —                                            | Valkey/Redis URL used for idempotency, deduplication, and caching. Some flows degrade or fail safely when it is unset. |
| `KEY_CACHE_TTL_SEC`             | `60`                                            | DICT key lookup cache TTL, in seconds.                                                                                 |

<Note>
  Identity values, URLs, and credentials declared on configuration components are used as **first-initialization seeds only**. After a key exists in the runtime store, restarting the service does not overwrite the value. Make later changes through the authenticated configuration plane.
</Note>

## Institution identity

| Variable           | Default / Required               | Description                                                |
| ------------------ | -------------------------------- | ---------------------------------------------------------- |
| `ORGANIZATION_ID`  | **Required for BYOC**            | UUID of the Midaz organization used by SPI, DICT, and COB. |
| `ISPB`             | **Required for BYOC**            | Eight-digit identifier of the participant institution.     |
| `ADAPTER_BASE_URL` | **Required for connected flows** | Connectivity adapter base URL used by SPI, DICT, and COB.  |

## Midaz and CRM

SPI uses Midaz for accounting. SPI and DICT use CRM to validate accounts and holders in flows that require this information.

| Variable              | Default / Required                  | Description                                                   |
| --------------------- | ----------------------------------- | ------------------------------------------------------------- |
| `MIDAZ_BASE_URL`      | **Required for accounting**         | Base URL shared by the Midaz onboarding and transaction APIs. |
| `MIDAZ_LEDGER_ID`     | **Required for accounting**         | UUID of the ledger that records Pix operations.               |
| `MIDAZ_CLIENT_ID`     | **Required with authentication**    | OAuth client ID used by SPI to call Midaz.                    |
| `MIDAZ_CLIENT_SECRET` | 🔒 **Required with authentication** | OAuth client secret used by SPI to call Midaz.                |
| `CRM_BASE_URL`        | **Required for validation flows**   | CRM base URL.                                                 |
| `CRM_CLIENT_ID`       | **Required with authentication**    | OAuth client ID used by SPI and DICT to call CRM.             |
| `CRM_CLIENT_SECRET`   | 🔒 **Required with authentication** | OAuth client secret used by SPI and DICT to call CRM.         |

## Cross-domain integrations

The URLs below point to deployed Pix Lerian components. They configure communication between SPI, DICT, COB, and the adapter without changing the contract consumed by the client application.

| Variable             | Default / Required                         | Description                                                                            |
| -------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
| `DICT_BASE_URL`      | **Required by components that query DICT** | DICT domain base URL. Used by SPI, COB, and the adapter.                               |
| `DICT_CLIENT_ID`     | **Required with authentication**           | OAuth client ID for DICT calls.                                                        |
| `DICT_CLIENT_SECRET` | 🔒 **Required with authentication**        | OAuth client secret for DICT calls.                                                    |
| `DICT_ROUTING_MODE`  | `hub`                                      | DICT discovery tier: `hub` or `proxy`. The configured URL must point to the same tier. |
| `COB_BASE_URL`       | **Required by components that query COB**  | COB domain base URL. Used by SPI and the adapter.                                      |
| `COB_CLIENT_ID`      | **Required with authentication**           | OAuth client ID for COB calls.                                                         |
| `COB_CLIENT_SECRET`  | 🔒 **Required with authentication**        | OAuth client secret for COB calls.                                                     |
| `COB_ROUTING_MODE`   | `hub`                                      | COB discovery tier: `hub` or `proxy`. The configured URL must point to the same tier.  |
| `SPI_BASE_URL`       | **Required by components that query SPI**  | SPI domain base URL. Used by DICT and the adapter.                                     |
| `SPI_CLIENT_ID`      | **Required with authentication**           | OAuth client ID for SPI calls.                                                         |
| `SPI_CLIENT_SECRET`  | 🔒 **Required with authentication**        | OAuth client secret for SPI calls.                                                     |

## DICT reconciliation (VSync)

The VSync worker reconciles the persisted DICT database with the regulatory source. RabbitMQ transport is enabled by default; when active, it requires a valid URI.

| Variable                              | Default / Required                           | Description                                                                 |
| ------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
| `VSYNC_ENABLED`                       | `true`                                       | Enables the reconciliation worker.                                          |
| `VSYNC_FILE_RECON_ENABLED`            | `true`                                       | Enables file-based reconciliation.                                          |
| `RABBITMQ_ENABLED`                    | `true`                                       | Enables the VSync RabbitMQ transport.                                       |
| `RABBITMQ_URI`                        | 🔒 **Required when `RABBITMQ_ENABLED=true`** | RabbitMQ connection URI. Use `amqps://` in production.                      |
| `VSYNC_CHUNK_CONSUMER_WORKERS`        | `3`                                          | Number of parallel chunk consumers.                                         |
| `VSYNC_JOBS_CONSUMER_WORKERS`         | `3`                                          | Number of parallel job consumers.                                           |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC`      | `120`                                        | Interval, in seconds, between stuck-job scans.                              |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30`                                         | Time, in minutes, before a chunk is considered stuck.                       |
| `VSYNC_MAX_JOB_ATTEMPTS`              | `3`                                          | Maximum number of reconciliation job attempts.                              |
| `VSYNC_EVENTSYNC_MAX_PAGES`           | `100`                                        | Maximum pages processed per event synchronization cycle.                    |
| `VSYNC_GATE_TTL_SEC`                  | `3600`                                       | TTL, in seconds, of the lock that protects mutations during reconciliation. |

## Streaming and observability

CloudEvents publishing from SPI, DICT, and COB uses the `STREAMING_*` family and remains disabled by default. When `STREAMING_ENABLED=true`, `STREAMING_BROKERS` is required. If you set `STREAMING_CLOUDEVENTS_SOURCE`, the only accepted value is `plugin-br-pix-lerian`. See [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox) and [Observability](/en/reference/byoc-configuration#observability) for the remaining broker, TLS, SASL, and OpenTelemetry parameters.

## Bootstrap configuration source

The delivered Helm chart `values.yaml` is the deployment bootstrap source. Keep it aligned with the chart version and preserve component-block and variable names. Inject secrets from the secret store and never store plaintext credentials in the repository. After seeding, use Systemplane to change runtime keys.

## Health and readiness

Configure probes through `<component>.livenessProbe.path` and `<component>.readinessProbe.path` in `values.yaml`. Default paths vary by component; do not assume unprefixed `/health` and `/readyz` paths.

The liveness probe checks whether the process is alive. The readiness probe checks whether required dependencies and configuration allow the component to receive traffic. Do not route traffic to a component until its readiness probe succeeds.