Environment variables

Pix Lerian components include the SPI, DICT Hub, COB Hub, their workers, and the connectivity adapter. This page lists the deployment inputs that the v1.0.0 release reads. Use the tables to see which values components share and which belong to one component. To install or upgrade Pix Lerian, see the Pix Lerian chart README.

Values shown here are placeholders. Inject credentials and license material from your secret store. Never commit real secrets. SYSTEMPLANE_SECRET_MASTER_KEY and VALKEY_URL are not part of the v1.0.0 contract.

Configuration model

Each component loads bootstrap values from its environment. The SPI, DICT Hub, COB Hub, and DICT VSync worker also consume runtime configuration from their Systemplane store after initialization. The mock provider adapter reads its configuration from the environment only and keeps its state in memory. Use the component-specific examples shipped with the release for SPI, DICT Hub, DICT VSync, and COB Hub. Configure each component separately. Their ports, stores, and required dependencies differ.

Pix Lerian v1.0.0 is available for integration and testing with the mock provider adapter. The native SPI messaging integration is not available for use in this release. Do not configure the mock adapter as a production rail.

Shared identity and deployment

Variable	Components	Contract
`APPLICATION_NAME`	All	Component identity used in logs, telemetry, and licensing. Keep the value supplied by the release configuration.
`SERVER_ADDRESS`	All HTTP components	Listen address in `host:port` format. The port must match the component service and probe configuration.
`DEPLOYMENT_MODE`	API components and workers	`local`, `saas`, or `byoc`. The default is `local` when the value is absent.
`REQUEST_TIMEOUT_SEC`	HTTP components	Per-request timeout in seconds. The default is `30`.
`LICENSE_KEY`	Licensed components	Optional in `local`; required in non-local deployment modes. Inject it as a secret.
`ORGANIZATION_IDS`	Licensed components	License scope, such as `global` or a comma-separated organization list.
`SWAGGER_ENABLED`	API components	Strict boolean. When unset, the runtime OpenAPI and Scalar surface is enabled outside production and disabled in production.

PLUGIN_AUTH_ENABLED controls inbound route authentication. PLUGIN_AUTH_HOST is the Access Manager base address used by the shared auth integration and OAuth client-credentials flows. It must be a base address only, without an OAuth path, query, fragment, or embedded credentials. Use https:// outside local development. The mock provider adapter requires SPI_BASE_URL, PROVIDER_CLIENT_ID, and PROVIDER_CLIENT_SECRET at boot. MOCK_TEST_ENDPOINTS_ENABLED=true turns on test routes that can forge provider callbacks. The mock adapter has no route authorization: keep it unreachable from untrusted callers, whatever this switch says.

Persistence and Valkey

Variable	Components	Contract
`DATABASE_URL`	SPI, DICT Hub, COB Hub, and VSync	PostgreSQL DSN for the component’s business store. It is required where that component persists business data.
`SYSTEMPLANE_POSTGRES_DSN`	Systemplane consumers	PostgreSQL DSN for the runtime configuration store. It falls back to `DATABASE_URL` in the API components when unset.
`REDIS_HOST`, `REDIS_PORT`, `REDIS_USER`, `REDIS_PASSWORD`, `REDIS_DB`	API components and VSync	Structured Valkey connection settings. Do not replace them with the retired `VALKEY_URL` variable.
`REDIS_TLS`, `REDIS_PROTOCOL`, `REDIS_CA_CERT`	API components and VSync	Valkey transport security. A private or self-signed certificate requires `REDIS_CA_CERT`; there is no skip-verification switch.
`KEY_CACHE_TTL_SEC`	DICT Hub	Pix-key cache TTL in seconds. The default is `60`.

Valkey behavior differs by component. SPI, DICT Hub, and COB Hub can degrade selected idempotency or cache paths when you do not configure Valkey. Some SPI, DICT, and COB mutations fail closed with PIX-0032 when no durable replay backstop exists. DICT VSync treats Valkey as a hard dependency because it coordinates the cross-pod mutation gate. A configured but malformed REDIS_* value fails boot rather than silently selecting a different endpoint. The v1.0.0 Systemplane implementation does not use SYSTEMPLANE_SECRET_MASTER_KEY. Protect Systemplane database access, backups, and disk storage through the deployment environment.

Institution and service integrations

Variable	Components	Contract
`ORGANIZATION_ID`	SPI, DICT Hub, COB Hub	Midaz organization the components use.
`ISPB`	SPI, DICT Hub, COB Hub	Participant identifier. The API validates the participant header or resolves the value from tenant configuration.
`ADAPTER_BASE_URL`	SPI, DICT Hub, COB Hub, VSync	Connectivity adapter base URL. For local integration, point it at the adapter-provider-mock service.
`MIDAZ_BASE_URL`	SPI	Midaz base URL for onboarding and transaction operations.
`MIDAZ_LEDGER_ID`	SPI	Ledger identifier used for accounting operations.
`MIDAZ_CLIENT_ID`, `MIDAZ_CLIENT_SECRET`	SPI	OAuth client credentials for Midaz calls.
`CRM_BASE_URL`, `CRM_CLIENT_ID`, `CRM_CLIENT_SECRET`	SPI, DICT Hub, VSync	CRM integration used by flows that validate accounts, holders, or orphaned entries.
`DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET`	SPI and COB Hub	DICT Hub or proxy address and credentials. `DICT_ROUTING_MODE` selects `hub` or `proxy`; keep the URL consistent with that choice.
`COB_BASE_URL`, `COB_CLIENT_ID`, `COB_CLIENT_SECRET`	SPI	COB Hub or proxy address and credentials. `COB_ROUTING_MODE` selects `hub` or `proxy`; keep the URL consistent with that choice.
`SPI_BASE_URL`, `SPI_CLIENT_ID`, `SPI_CLIENT_SECRET`	DICT Hub	SPI address and credentials used for transfer lookups and MED 2.0 balance-lock operations.

These are service-to-service settings. They do not make the native SPI connector available. That integration is not part of the usable v1.0.0 release surface.

DICT VSync

The DICT VSync worker reconciles DICT state and requires its own worker configuration:

Variable	Default	Contract
`VSYNC_ENABLED`	`true`	Enables the worker scheduler.
`VSYNC_FILE_RECON_ENABLED`	`true`	Enables file-based reconciliation.
`VSYNC_CHUNK_PROCESSING_DEADLINE_MIN`	`30`	Chunk processing deadline in minutes.
`VSYNC_MAX_JOB_ATTEMPTS`	`3`	Maximum attempts for a reconciliation job.
`VSYNC_EVENTSYNC_MAX_PAGES`	`100`	Maximum pages in event synchronization.
`VSYNC_GATE_TTL_SEC`	`3600`	Mutation-gate lease TTL in seconds.
`VSYNC_STUCK_JOB_SWEEP_TICK_SEC`	`120`	Interval between stuck-job scans in seconds.
`RABBITMQ_URI`	—	RabbitMQ URI for the file-reconciliation queue. Use `amqps://` outside local development.
`RABBITMQ_ENABLED`	component-dependent	Enables the DICT Hub jobs publisher. The VSync worker itself requires its queue configuration.

VSYNC_ENABLED and VSYNC_FILE_RECON_ENABLED can be hot-reloaded through the worker’s runtime configuration. The remaining tuning values are read at boot and require a restart.

Streaming and observability

The notification-outbox relay is disabled by default. To enable it, set STREAMING_ENABLED=true and provide STREAMING_BROKERS. The shared CloudEvents source, when configured, must identify the Pix Lerian service. The component also validates the streaming broker’s TLS/SASL settings and the optional STREAMING_DATASCHEMA_BASE_URL. Set ENABLE_TELEMETRY=true to turn on OpenTelemetry. The OTEL_* variables configure it. See BYOC configuration for shared telemetry and broker transport parameters.

Health and readiness

Probe paths and route prefixes belong to the component deployment configuration. Do not assume that every component exposes unprefixed /health or /readyz. Use the paths in the release chart and component bootstrap configuration.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Environment variables

Configuration model

Shared identity and deployment

Persistence and Valkey

Institution and service integrations

DICT VSync

Streaming and observability

Health and readiness

​Configuration model

​Shared identity and deployment

​Persistence and Valkey

​Institution and service integrations

​DICT VSync

​Streaming and observability

​Health and readiness

Configuration model

Shared identity and deployment

Persistence and Valkey

Institution and service integrations

DICT VSync

Streaming and observability

Health and readiness