> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# BYOC configuration essentials

> The environment variables shared across Lerian Go services, with their possible values — the backbone knobs an operator sets when deploying into their own cloud or on-prem infrastructure (BYOC).

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.

<Note>
  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](#per-product-variables) for the exhaustive lists.
</Note>

## 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`](/en/reference/health-and-readiness) 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`         |

<Warning>
  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.
</Warning>

## 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                    |

<Note>
  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](/en/reference/default-network-ports) and [Health and readiness](/en/reference/health-and-readiness).
</Note>

## 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                                  |

<Note>
  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).
</Note>

## 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     |

<Note>
  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.
</Note>

## 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](/en/reference/systemplane/overview) 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`                         |

<Note>
  `STREAMING_SASL_*` and `STREAMING_TLS_*` secure the broker connection — set them when your broker requires authentication or TLS.
</Note>

## 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          |

<Note>
  Some services use legacy aliases (`SD_ADVERTISE_*`, `CONSUL_ADDR`) for the same behavior.
</Note>

## Observability

Telemetry is push-based (OTLP). Some services additionally expose a `/metrics` endpoint for Prometheus scraping — see [Health and readiness](/en/reference/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:

<CardGroup cols={2}>
  <Card title="Midaz" href="/en/midaz/midaz-environment-variables" />

  <Card title="Tracer" href="/en/tracer/tracer-environment-variables" />

  <Card title="Reporter" href="/en/reporter/reporter-environment-variables" />

  <Card title="Flowker" href="/en/flowker/flowker-environment-variables" />

  <Card title="Lender" href="/en/lender/configuration-and-deploy" />

  <Card title="Fetcher" href="/en/fetcher/fetcher-configuration" />
</CardGroup>

<Note>
  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.
</Note>