Environment variables

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.

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.

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:

Render the release

Helm creates each component’s ConfigMap and references its Secret. The Deployment loads both with envFrom when the pod starts.

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.

Consume the configuration

Domain APIs and workers read the Systemplane store. Each key definition determines whether it supports runtime updates or requires a restart.

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.

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_*.

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.

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

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.

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

Overview

Lerian SPI — native messaging

JD — interface (direct Pix)

BTG — interface (indirect Pix)

Environment variables

How `values.yaml` and Systemplane work together

Server and deployment mode

Persistence and runtime configuration

Institution identity

Midaz and CRM

Cross-domain integrations

DICT reconciliation (VSync)

Streaming and observability

Bootstrap configuration source

Health and readiness

​How values.yaml and Systemplane work together

​Server and deployment mode

​Persistence and runtime configuration

​Institution identity

​Midaz and CRM

​Cross-domain integrations

​DICT reconciliation (VSync)

​Streaming and observability

​Bootstrap configuration source

​Health and readiness

How `values.yaml` and Systemplane work together

Server and deployment mode

Persistence and runtime configuration

Institution identity

Midaz and CRM

Cross-domain integrations

DICT reconciliation (VSync)

Streaming and observability

Bootstrap configuration source

Health and readiness