Configuration and deploy

Lender is a single Go service, packaged as a container and configured entirely through environment variables. This page is the operator’s reference: what it runs as, what it depends on, the settings that matter, and how tenancy and ledger routing behave.

The container

Lender builds from a multi-stage Dockerfile (a Go Alpine builder producing a static binary, copied into a distroless nonroot runtime) and listens on port 8080. It ships as a container image you deploy into your cluster with the platform’s standard lifecycle tooling. This page does not assume any particular packaging beyond the image. Operational probes:

Endpoint	Purpose
`GET /health`	Liveness.
`GET /readyz`	Dependency readiness.
`GET /version`	Build and version metadata.

Dependencies

Dependency	Role
PostgreSQL 17	Primary data store, with primary/replica support and schema-per-tenant isolation in multi-tenant mode.
Valkey 8 (Redis-compatible)	Cache, rate limiting, and the M2M-credential cache.
RabbitMQ	Separate messaging transport for non-lifecycle subsystems; it is not the transport for Lender’s lifecycle fact catalog.
RedPanda	Kafka-compatible streaming backbone for lifecycle facts, published through Lerian’s streaming library and transactional outbox.
Midaz	The double-entry , reached through the official SDK. Lender authenticates via Access Manager with per-tenant machine-to-machine (M2M) credentials, retrieved from the configured custody backend — AWS Secrets Manager by default or HashiCorp Vault KV v2 when selected — and cached in Valkey.
Caradhras	Identity backend behind Access Manager. Route authorization runs through Lerian’s auth library.
Systemplane	Runtime configuration plane, mounted under `/api/v1/systemplane`.

Configuration surface

Configuration is entirely environment-driven. The keys below shape behavior. They are not the full list.

Group	Key	What it controls
App	`ENV_NAME`, `LOG_LEVEL`, `DEPLOYMENT_MODE`, `SERVER_ADDRESS`	Environment name, log verbosity, deployment mode, and listen address.
Tenancy	`MULTI_TENANT_ENABLED`, `DEFAULT_TENANT_ID`	Switch between single- and multi-tenant modes, and the tenant used when single-tenant.
Tenancy (MT)	`MULTI_TENANT_MAX_TENANT_POOLS`, `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	Per-tenant connection-pool ceiling and circuit-breaker trip point.
Postgres	`POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_NAME`, `POSTGRES_SSLMODE`	Primary database connection. Migration directories are fixed in the service image, not configurable.
Cache	`REDIS_HOST`, `REDIS_PASSWORD`, `M2M_CREDENTIAL_CACHE_TTL_SEC`	Valkey connection and how long M2M credentials are cached.
Messaging	`RABBITMQ_ENABLED`, `RABBITMQ_HOST`, `OUTBOX_DISPATCH_INTERVAL_SEC`	Separate RabbitMQ messaging path and dispatcher cadence. These variables do not configure lifecycle event topics. The PostgreSQL outbox is always initialized; it has no enable flag.
Streaming	`STREAMING_ENABLED`, `STREAMING_BROKERS`, `STREAMING_TLS_ENABLED`, `STREAMING_TLS_CA_CERT`	Lifecycle event streaming toggle, Kafka-compatible broker addresses, TLS, and an optional base64-encoded PEM CA certificate for private broker trust. Invalid base64 or decoded non-PEM content prevents startup.
Auth	`PLUGIN_AUTH_ENABLED`, `AUTH_M2M_INVERSION_ENABLED`	Route authorization and the required M2M-inversion gate for BYOC.
Proxy security	`TLS_TERMINATED_UPSTREAM`, `TRUST_PROXY_ENABLED`, `TRUSTED_PROXIES`	Upstream TLS termination and the restrictive trusted-proxy list it requires in hardened deployments.
Consignado	`CONSIGNADO_ENABLED`	Defaults to `true`. It gates the legacy inbound `consignado.averbacao.rejected` handling only: the contratação route, CCB signer, and averbação-confirmed consumer are retired. When you disable it, also keep `CONSUMER_CONSIGNADO_AVERBACAO_REJECTED_ENABLED` off; startup rejects that contradictory configuration. Existing-contract servicing and the replacement booking and payment paths configure independently. See Consignado privado.
Ledger M2M custody	`M2M_SECRETS_BACKEND`, `M2M_VAULT_MOUNT`, `AWS_REGION`	Credential custody backend (AWS by default or HashiCorp Vault KV v2), its KV mount, and the AWS region when AWS is selected.
Ledger accounts	`MIDAZ_LEDGER_ACCOUNT_PROVISIONING_ENABLED`	Defaults to `true`. Before a relay posts, Lender ensures the non-external account aliases from the accounting profile exist; disable it only when you pre-provision the chart of accounts. It never creates assets.
Observability	`ENABLE_TELEMETRY`, `OTEL_EXPORTER_OTLP_ENDPOINT`	Telemetry toggle and OTLP collector endpoint.
Limits	`RATE_LIMIT_ENABLED`	Request rate limiting. Always on when `ENV_NAME=production`.
Docs	`SWAGGER_ENABLED`	Serve the OpenAPI document and API reference UI. Always off when `ENV_NAME=production`.

Multi-tenant modes

Lender runs in one of two modes:

Single-tenant: one tenant (DEFAULT_TENANT_ID), one database schema, and a construction-time ledger organization and ledger used as the posting default.
Multi-tenant (MULTI_TENANT_ENABLED=true): schema-per-tenant persistence, a per-tenant Midaz client pool, and tenant-scoped events and postings. In this mode there is no env ledger default: the ledger target comes per transaction from the product’s accounting profile.

Ledger posting and fails-closed routing

A booking reaches the ledger through a durable posting intent and an asynchronous relay. The full path is in Lender in the platform. Routing fails closed. A posting books into the ledger organization and ledger resolved from the accounting profile. In single-tenant mode, a posting that resolves no profile target falls back to the env default. If neither resolves a non-empty target, Lender refuses to post rather than book into an empty or wrong ledger. Under multi-tenant mode, a product with no accounting profile therefore cannot post. That safeguard is intentional.

Next steps

Lender in the platform

The posting path, event catalog, and tenant isolation in detail.

Overview

Getting started

Concepts

Guides

Integration

Operations

Configuration and deploy

The container

Dependencies

Configuration surface

Multi-tenant modes

Ledger posting and fails-closed routing

Next steps

Lender in the platform

​The container

​Dependencies

​Configuration surface

​Multi-tenant modes

​Ledger posting and fails-closed routing

​Next steps

Lender in the platform

The container

Dependencies

Configuration surface

Multi-tenant modes

Ledger posting and fails-closed routing

Next steps