BYOC configuration essentials

Shared environment variables used across Lerian Go services: the deployment-wide backbone operators set when running BYOC in their own cloud or on-prem.

In a BYOC (bring your own cloud) deployment, you run Lerian products inside your own AWS, GCP, or on-prem infrastructure. You own the data and the runtime. You configure each service through environment variables, and most of them are service-specific. This page covers the universal backbone: the variables that behave the same way across Lerian Go services. Set the deployment-wide knobs once, then use each product’s own page for the rest.

For Pix Lerian v1.0.0, BYOC configuration supports its delivered components and mock-adapter integration/testing lane. It does not make the native SPI messaging connector available or make the mock adapter a production rail.

These variables form the shared backbone, not the full list. Variable prefixes differ slightly between services (for example, a service with separate onboarding and transaction databases namespaces them), and every service adds its own keys. See Per-product variables for the exhaustive lists.

Deployment mode and TLS

DEPLOYMENT_MODE sets how strictly the service enforces TLS on its infrastructure connections. The /readyz response reports its value.

Variable	Description	Default	Allowed values
DEPLOYMENT_MODE	TLS-enforcement posture. local allows plaintext connections. byoc recommends TLS and warns on plaintext but still boots. saas makes TLS mandatory — the service refuses to start if any dependency connection lacks TLS.	local	local, byoc, saas
ALLOW_INSECURE_TLS	Bypass per-connection TLS enforcement on infrastructure DSNs. Intended for local development only.	false	true, false

For a production BYOC deployment, set DEPLOYMENT_MODE=byoc, connect every datastore over TLS, and leave ALLOW_INSECURE_TLS unset (false). The local defaults ship plaintext connections and are not safe for production.

Server

Variable	Description	Default	Allowed values
SERVER_ADDRESS	Main HTTP listen address (host:port, usually :port). The liveness, readiness, and version probes bind this same port.	Varies per service	host:port
LOG_LEVEL	Log verbosity. Use info or higher in production.	debug	debug, info, warn, error
ENV_NAME	Environment label. In SLC, it is normalized to an allowlist.	development	SLC: production, staging, uat, development, local
VERSION	Service version tag surfaced by /version.	Per release	Semver string

Some services expose a numeric SERVER_PORT instead of, or alongside, SERVER_ADDRESS. Worker components without a primary HTTP API expose a dedicated health port (for example HEALTH_PORT or WORKER_SERVER_PORT). See Default network ports and Health and readiness.

Datastores

Every service that persists state connects to one or more datastores. The variable prefix depends on the store, and in some services on the logical database. The table below shows the common shape. Consult each product’s page for the exact names.

Variable	Description	Default	Allowed values
POSTGRES_HOST / POSTGRES_PORT	PostgreSQL host and port.	— / 5432	Host / port
POSTGRES_USER / POSTGRES_PASSWORD	Connection credentials. The password is a secret — inject it at deploy time, never commit it.	—	String / secret
POSTGRES_NAME / POSTGRES_DB / DB_NAME	Database name. The exact key varies by service — POSTGRES_NAME (for example STA, SLC, SISBAJUD, Consignado), POSTGRES_DB (SPB, SPI, Boleto), or DB_NAME (Pix Indirect); Midaz namespaces it per logical database as DB_{MODULE}_NAME. Consult each product’s page.	—	String
POSTGRES_SSLMODE	libpq TLS mode. Use require or stronger in production.	disable	disable, require, verify-ca, verify-full
POSTGRES_REPLICA_*	Optional read-replica connection (same shape as the primary).	—	Host / port / credentials
MONGO_URI / MONGO_HOST / MONGO_PORT	MongoDB connection, as a full URI or discrete host and port.	—	Connection string / host / port
MONGO_TLS_CA_CERT	Base64-encoded PEM CA certificate for TLS (for example, a managed MongoDB service).	—	Base64 PEM
REDIS_HOST / REDIS_PASSWORD	Redis/Valkey endpoint and auth password (secret).	—	host:port / secret
REDIS_TLS / REDIS_CA_CERT	Enable TLS to Redis and supply a base64-encoded PEM CA certificate. In SLC, REDIS_TLS=true requires a nonblank REDIS_CA_CERT.	false / —	true, false / base64 PEM
RABBITMQ_HOST / RABBITMQ_URI	Broker host and connection scheme. Use amqps in production.	— / amqp	Host / amqp, amqps
RABBITMQ_DEFAULT_USER / RABBITMQ_DEFAULT_PASS	Broker credentials (password is a secret). In SLC, when RabbitMQ is enabled and its URL has no credentials, explicitly declare both RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS.	—	String / secret

Not every service uses every store, and prefixes vary. Core products often namespace connections per logical database (for example DB_ONBOARDING_*, DB_TRANSACTION_*, MONGO_CRM_*). Plugins and rails use the flat POSTGRES_* shape above. In multi-tenant mode, the service ignores static datastore credentials and resolves connections per tenant (see below).

Multi-tenancy

Multi-tenancy is off by default. When you enable it, every datastore connection switches from static configuration to per-tenant resolution through Tenant Manager. The service also adds a per-tenant readiness probe at GET /readyz/tenant/{id}.

Variable	Description	Default	Allowed values
MULTI_TENANT_ENABLED	Enable per-tenant connection resolution. When false, the service runs single-tenant with the static connections above.	false	true, false
MULTI_TENANT_URL	Tenant Manager API URL. Required when enabled.	—	URL
MULTI_TENANT_SERVICE_API_KEY	API key for Tenant Manager (secret). Required when enabled.	—	Secret
MULTI_TENANT_ALLOW_INSECURE_HTTP	Allow a cleartext http:// Tenant Manager URL. Never enable in production — credentials travel in plaintext.	false	true, false
MULTI_TENANT_REDIS_HOST / MULTI_TENANT_REDIS_PORT	Optional Redis endpoint for tenant lifecycle events (event-driven discovery).	— / 6379	Host / port

Additional per-tenant pool sizing, circuit-breaker, and cache-TTL knobs (MULTI_TENANT_MAX_TENANT_POOLS, MULTI_TENANT_CIRCUIT_BREAKER_*, MULTI_TENANT_CACHE_TTL_SEC, and others) exist per service. See the per-product pages.

Runtime configuration

Variable	Description	Default	Allowed values
SYSTEMPLANE_ENABLED	Enable the systemplane runtime-configuration admin API on the main port. Off by default in most services; some — for example SPI — enable it by default. Check each service’s page.	false (SPI: true)	true, false

When enabled, the service exposes an authenticated plane for reading and writing runtime configuration. See Systemplane for the API, namespaces, and required permissions.

Streaming and outbox

The event-publication path (a lib-streaming producer backed by a transactional outbox) is off by default in most services. The exception is the native rails (for example SPI and SILOC), which do not expose STREAMING_ENABLED at all. Streaming on those rails has no disabled mode: STREAMING_BROKERS is mandatory, and the service refuses to start when that value is absent or invalid. Check each product’s page for its contract.

Variable	Description	Default	Allowed values
STREAMING_ENABLED	Enable the event producer, in services that expose the switch. The native rails do not read this variable: their streaming is always on.	false	true, false
STREAMING_BROKERS	Kafka/RedPanda bootstrap brokers, as a host:port comma-separated list. Required at startup by services whose streaming has no disabled mode.	—	host:port CSV
STREAMING_CLOUDEVENTS_SOURCE	The CloudEvents source stamped on every event the service emits. It has no default: a producer that streams to a broker with this value empty stops at startup. Several products accept exactly one literal and refuse to boot on any other, so take the value from the product’s own page.	—	The literal the product requires
STREAMING_EVENT_POLICIES	Per-event delivery-policy overrides, as event.key.attribute=value entries separated by commas, semicolons, or newlines (for example transaction.created.enabled=true,transaction.created.outbox=always). The attributes are enabled, direct, outbox, and dlq. Empty keeps each event’s default policy.	—	event.key.attribute=value list
STREAMING_COMPRESSION	Producer compression codec.	lz4	none, gzip, snappy, lz4, zstd
STREAMING_REQUIRED_ACKS	Producer acknowledgement level.	all	all, leader, none
OUTBOX_ENABLED	Enable the transactional outbox dispatcher (where the service exposes it separately).	false	true, false

STREAMING_SASL_* and STREAMING_TLS_* secure the broker connection. Set them when your broker requires authentication or TLS.

Service discovery

Consul service discovery is off by default. When enabled, the service registers itself and resolves peers through Consul instead of static addresses.

Variable	Description	Default	Allowed values
SD_ENABLED	Enable Consul service discovery.	false	true, false
SD_ADDRESS	Consul agent address. Required when enabled.	—	host:port
SD_EXTERNAL_ADDRESS / SD_INTERNAL_ADDRESS	Advertised addresses. Required when enabled.	—	host:port
SD_TLS / SD_TLS_SKIP_VERIFY	Enable TLS to Consul, and (separately) bypass certificate verification.	false	true, false
SD_TOKEN	Consul ACL token (secret).	—	Secret

Some services use legacy aliases (SD_ADVERTISE_*, CONSUL_ADDR) for the same behavior.

Observability

Telemetry is push-based (OTLP). Some services additionally expose a /metrics endpoint for Prometheus scraping. See Health and readiness.

Variable	Description	Default	Allowed values
ENABLE_TELEMETRY	Enable OpenTelemetry instrumentation.	false	true, false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint. Required when telemetry is enabled.	—	URL
OTEL_EXPORTER_OTLP_PORT	OTLP port, when using a discrete host and port.	4317	Port
OTEL_RESOURCE_SERVICE_NAME	Service name attached to exported telemetry.	Service default	String
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Environment label attached to exported telemetry.	—	String
OTEL_INSECURE_EXPORTER	Allow a plaintext OTLP connection. Leave false in production.	false	true, false

Plugin authentication

Lerian services can authenticate protected routes, including the systemplane admin API, through Access Manager (Caradhras-backed). The authentication toggle, its variable name, and its default differ by service. Most plugins and products use PLUGIN_AUTH_ENABLED (default false, off). Native rails such as SILOC and SPB use AUTH_ENABLED (default true, on, required in production and SaaS) paired with AUTH_ADDRESS. Always enable authentication in production. Check each product or rail’s own environment-variables page for the authoritative toggle name, its default, and the routes it protects.

Variable	Description	Default	Allowed values
PLUGIN_AUTH_ENABLED / AUTH_ENABLED	Require Access Manager authentication on protected routes. The name and default vary by service — plugins use PLUGIN_AUTH_ENABLED, native rails use AUTH_ENABLED.	Plugins false, rails true	true, false
PLUGIN_AUTH_ADDRESS / PLUGIN_AUTH_HOST / AUTH_ADDRESS	Access Manager service address. Required when enabled.	—	Address

Per-product variables

The variables above form the shared baseline. Each product adds its own: datastore prefixes, integration URLs, worker tuning, and feature toggles. Use the per-product pages for the full, current list:

Midaz

Tracer

Reporter

Flowker

Lender

The exhaustive, per-service variable list ships in each service’s .env.example file. Treat it as the source of truth for a specific release, and never commit real secret values into it.