BYOC configuration essentials

In a BYOC (bring your own cloud) deployment, you run Lerian products inside your own AWS, GCP, or on-prem infrastructure and own the data and the runtime. Each service is configured 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 — so you can set the deployment-wide knobs once and then reach for each product’s own page for the rest.

This is 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, and its value is echoed in the /readyz response.

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. Some services arm stricter security gates when this is set to `production`.	`development`	Free string
`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.	`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).	—	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_*), while plugins and rails use the flat POSTGRES_* shape above. In multi-tenant mode, static datastore credentials are ignored — connections are resolved 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, and the service 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 every service except the Fetcher worker, which sets STREAMING_ENABLED=true to emit job-completion events.

Variable	Description	Default	Allowed values
`STREAMING_ENABLED`	Enable the event producer.	`false` (Fetcher worker: `true`)	`true`, `false`
`STREAMING_BROKERS`	Kafka/RedPanda bootstrap brokers, as a `host:port` comma-separated list.	—	`host:port` CSV
`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 (Casdoor-backed). The authentication toggle, its variable name, and its default differ by service: most plugins and products use PLUGIN_AUTH_ENABLED (default false, off), while 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, and 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 are 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

Fetcher

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.

Overview

Integration essentials

Stability & quality

BYOC configuration essentials

Deployment mode and TLS

Server

Datastores

Multi-tenancy

Runtime configuration

Streaming and outbox

Service discovery

Observability

Plugin authentication

Per-product variables

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

​Deployment mode and TLS

​Server

​Datastores

​Multi-tenancy

​Runtime configuration

​Streaming and outbox

​Service discovery

​Observability

​Plugin authentication

​Per-product variables

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

Deployment mode and TLS

Server

Datastores

Multi-tenancy

Runtime configuration

Streaming and outbox

Service discovery

Observability

Plugin authentication

Per-product variables