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

# TED Lerian environment variables

> Environment variables that TED Lerian reads at startup: server, authentication, datastores, Midaz, Lerian SPB, policy, idempotency, events and telemetry.

TED Lerian reads these variables when the service starts. A change takes effect after you restart the service. Runtime settings, such as the address of Lerian SPB and the fee estimate package, are not environment variables.

In the tables, **Required** marks a variable that you must set, always or under the condition named. `—` means no default.

> [!NOTE]
>
> With `ENVIRONMENT_NAME=production`, the service does not start unless all of these are true: `POSTGRES_PASSWORD` is set, `POSTGRES_SSLMODE` is not `disable`, `PLUGIN_AUTH_ENABLED` is `true`, `TRUSTED_PROXIES` is set, `REDIS_TLS` is `true`, `AUDIT_MONGO_URI` asks for TLS, and neither `ALLOW_CORS_WILDCARD` nor `ALLOW_RATELIMIT_FAIL_OPEN` is `true`.

## Runtime and server

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENVIRONMENT_NAME` | Environment name. `production` turns on the startup checks in the note above. `ENV_NAME` is read when `ENVIRONMENT_NAME` is not set. | `development` | No |
| `DEPLOYMENT_MODE` | `local`, `byoc` or `saas`. | `local` | No |
| `LOG_LEVEL` | Log level. | `info` | No |
| `SERVER_ADDRESS` | HTTP listen address. | `:8080` | No |
| `HTTP_BODY_LIMIT_BYTES` | Largest body the HTTP server accepts, in bytes. A larger body gets `413` `TED-9003`. | `104857600` | No |
| `SERVER_TLS_CERT_FILE`, `SERVER_TLS_KEY_FILE` | Certificate and key for TLS on the service itself. Set both or neither. | — | No |
| `TLS_TERMINATED_UPSTREAM` | `true` when a proxy in front of the service ends TLS. The service then listens on plain HTTP. | `false` | No |
| `TRUSTED_PROXIES` | Comma-separated IPs or CIDRs of the proxies in front of the service. The service uses them to find the client IP. | — | In production |
| `CORS_ALLOWED_ORIGINS` | Allowed CORS origins. | `http://localhost:3000` | No |
| `CORS_ALLOWED_METHODS` | Allowed CORS methods. | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | No |
| `CORS_ALLOWED_HEADERS` | Allowed CORS headers. | `Origin,Content-Type,Accept,Authorization,X-Request-ID` | No |
| `CORS_EXPOSE_HEADERS` | Headers exposed to the browser. | — | No |
| `CORS_ALLOW_CREDENTIALS` | Allow credentials on CORS requests. | `false` | No |
| `SWAGGER_ENABLED` | Serve the OpenAPI document of the service. | `false` | No |
| `SYSTEMPLANE_ENABLED` | Turn on the runtime settings and their API. | `false` | To send TEDs |
| `INFRA_CONNECT_TIMEOUT_SEC` | Time limit to connect to the datastores at startup, in seconds. | `30` | No |

## Authentication and license

| Variable | Description | Default | Required |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Check the Access Manager token and permission on each call. | `true` | No |
| `PLUGIN_AUTH_HOST` | Access Manager base address, an absolute `http` or `https` URL. TED Lerian also gets from it the token for its calls to the CRM and to Lerian SPB. | — | Yes |
| `CRM_CLIENT_ID`, `CRM_CLIENT_SECRET` | Access Manager application that TED Lerian uses for its calls to the CRM and to Lerian SPB. The secret is sensitive. | — | Yes |
| `LICENSE_ENABLED` | Check the product license for each organization. | `false` | No |
| `LICENSE_APPLICATION_ID` | Application name sent to the license check. | `plugin-br-ted-lerian` | No |
| `LICENSE_KEY` | License key that the license check uses. Sensitive. | — | No |
| `ORGANIZATION_IDS` | Comma-separated organizations that the license covers. | — | No |

## PostgreSQL

| Variable | Description | Default | Required |
| - | - | - | - |
| `POSTGRES_HOST` | Primary host. | `localhost` | No |
| `POSTGRES_PORT` | Primary port. | `5432` | No |
| `POSTGRES_USER` | Database user. | `plugin-br-ted-lerian` | No |
| `POSTGRES_PASSWORD` | Database password. Sensitive. | — | In production |
| `POSTGRES_NAME` | Database name. | `plugin-br-ted-lerian` | No |
| `POSTGRES_SSLMODE` | libpq TLS mode. | `disable` | No |
| `POSTGRES_REPLICA_HOST`, `POSTGRES_REPLICA_PORT`, `POSTGRES_REPLICA_USER`, `POSTGRES_REPLICA_PASSWORD`, `POSTGRES_REPLICA_NAME`, `POSTGRES_REPLICA_SSLMODE` | Optional read replica, with the same meaning as the primary values. | — | No |
| `POSTGRES_MAX_OPEN_CONNS` | Largest number of open connections. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Largest number of idle connections. | `5` | No |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Connection lifetime, in minutes. | `30` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Idle time before a connection closes, in minutes. | `5` | No |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Connection time limit, in seconds. | `10` | No |

## Valkey

Valkey keeps the idempotency records, the rate-limit counters and the usage-limit counters.

| Variable | Description | Default | Required |
| - | - | - | - |
| `REDIS_HOST` | Address, `host:port`. | `localhost:6379` | No |
| `REDIS_MASTER_NAME` | Sentinel master name, when you use Sentinel. | — | No |
| `REDIS_PASSWORD` | Password. Sensitive. | — | No |
| `REDIS_DB` | Database number. | `0` | No |
| `REDIS_PROTOCOL` | Protocol version. | `3` | No |
| `REDIS_TLS` | Connect with TLS. | `false` | In production |
| `REDIS_CA_CERT` | CA bundle, base64-encoded, for a server certificate from a private CA. | — | No |
| `REDIS_POOL_SIZE` | Connection pool size. | `10` | No |
| `REDIS_MIN_IDLE_CONNS` | Smallest number of idle connections. | `2` | No |
| `REDIS_READ_TIMEOUT`, `REDIS_WRITE_TIMEOUT` | Read and write time limits, in seconds. | `3` | No |
| `REDIS_DIAL_TIMEOUT` | Connection time limit, in seconds. | `5` | No |
| `REDIS_POOL_TIMEOUT` | Wait for a free connection, in seconds. | `2` | No |
| `REDIS_MAX_RETRIES` | Retries of a failed command. | `3` | No |
| `REDIS_MIN_RETRY_BACKOFF` | Shortest wait between retries, in milliseconds. | `8` | No |
| `REDIS_MAX_RETRY_BACKOFF` | Longest wait between retries, in seconds. | `1` | No |

## Audit trail

| Variable | Description | Default | Required |
| - | - | - | - |
| `AUDIT_MONGO_URI` | MongoDB connection string of the audit trail. In production, it must ask for TLS (`tls=true`, or a `mongodb+srv://` URI). | — | Yes |

## Midaz

TED Lerian holds, settles and credits the money in the Midaz ledger, and finds accounts and holders in the CRM.

| Variable | Description | Default | Required |
| - | - | - | - |
| `MIDAZ_LEDGER_ENABLED` | Connect to the Midaz ledger. Without it, TED Lerian cannot move money in Midaz. | `false` | No |
| `MIDAZ_LEDGER_BASE_URL` | Base address of the Midaz ledger. | — | No |
| `MIDAZ_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID` | Organization and ledger of this installation. TED Lerian credits incoming TEDs there, and an ISPB binding must point to this pair. | — | If the ledger is enabled |
| `MIDAZ_ACCESS_MANAGER_ADDRESS` | Access Manager address for the calls to the Midaz ledger. | — | If the ledger is enabled, unless `MIDAZ_ANONYMOUS` is `true` |
| `MIDAZ_CLIENT_ID`, `MIDAZ_CLIENT_SECRET` | Access Manager application for the calls to the Midaz ledger. The secret is sensitive. | — | If the ledger is enabled, unless `MIDAZ_ANONYMOUS` is `true` |
| `MIDAZ_ANONYMOUS` | Call a local Midaz that has no authentication. For local development only. | `false` | No |
| `MIDAZ_IDEMPOTENCY_TTL_SECONDS` | How long Midaz keeps the idempotency key of each ledger call, in seconds, from `3600` to `604800`. A value outside that range stops the startup. | `86400` | No |
| `MIDAZ_CRM_ENABLED` | Connect to the CRM, where TED Lerian finds accounts and holders. | `false` | No |
| `MIDAZ_CRM_BASE_URL` | CRM base address, an absolute `http` or `https` URL. It must be `https` when `ENVIRONMENT_NAME` is not `development`, `local`, `test` or `ci`. | — | If the CRM is enabled |

## Lerian SPB

The address of Lerian SPB is a runtime setting of each institution. `RAIL_ALLOWED_HOSTS` limits the hosts that TED Lerian accepts there.

| Variable | Description | Default | Required |
| - | - | - | - |
| `RAIL_ALLOWED_HOSTS` | Comma-separated `host:port` values of Lerian SPB. TED Lerian does not call a Lerian SPB address on any other host. | — | Yes |
| `CIRCUIT_BREAKER_ENABLED` | Protect the calls to Lerian SPB with a circuit breaker. | `false` | No |

## Policy and operations

| Variable | Description | Default | Required |
| - | - | - | - |
| `POLICY_USAGE_LIMITS_MODE` | `enforced` applies the usage limits. `disabled` refuses every send with `TED-0080`. `noop` checks no limit. Any other value stops the startup. | `enforced` | No |
| `RECONCILIATION_QUEUE_CURSOR_KEY` | Key that signs the cursors of the reconciliation queue: the base64 of exactly 32 bytes. Sensitive. A new key makes the cursors in use invalid. | — | Yes |

## Idempotency and rate limits

| Variable | Description | Default | Required |
| - | - | - | - |
| `IDEMPOTENCY_MIN_TTL_SEC`, `IDEMPOTENCY_MAX_TTL_SEC` | Lowest and highest `X-TTL` that the service accepts, in seconds. A value outside them is adjusted to them. | `30`, `604800` | No |
| `RATE_LIMIT_ENABLED` | Turn on the rate limits. | `true` | No |
| `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_SEC` | Requests allowed in each window, and the window in seconds, for the standard routes. | `500`, `60` | No |
| `AGGRESSIVE_RATE_LIMIT_MAX`, `AGGRESSIVE_RATE_LIMIT_WINDOW_SEC` | The same, for the strict routes. | `100`, `60` | No |
| `RELAXED_RATE_LIMIT_MAX`, `RELAXED_RATE_LIMIT_WINDOW_SEC` | The same, for the relaxed routes. | `1000`, `60` | No |

## Events

TED Lerian writes each event in its outbox, in the same transaction as the status change. The outbox relay then publishes it. The broker connection comes from the shared `STREAMING_*` settings in [Streaming and outbox](https://docs.lerian.studio/en/reference/byoc-configuration.md#streaming-and-outbox).

| Variable | Description | Default | Required |
| - | - | - | - |
| `STREAMING_ENABLED` | Publish events. It requires `OUTBOX_ENABLED=true`. | `false` | No |
| `STREAMING_CLOUDEVENTS_SOURCE` | CloudEvents source. It must be `br-ted` when streaming is on. | — | If streaming is on |
| `STREAMING_HEALTH_CHECK_TIMEOUT` | Time limit of the broker readiness check (Go duration). | `2s` | No |
| `OUTBOX_ENABLED` | Turn on the outbox relay. | `false` | If streaming is on |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | Time between relay cycles while events wait, in seconds. | `2` | No |
| `OUTBOX_COLD_DISPATCH_INTERVAL_SEC` | Time between relay cycles while the outbox has no recent activity, in seconds. The first event after an idle period can wait this long. | `60` | No |
| `OUTBOX_BATCH_SIZE` | Largest number of events in one cycle. | `50` | No |
| `OUTBOX_PUBLISH_MAX_ATTEMPTS` | Publish attempts for each event. | `3` | No |
| `OUTBOX_PUBLISH_BACKOFF_MS` | Base wait between publish attempts, in milliseconds. | `200` | No |
| `OUTBOX_RETRY_WINDOW_SEC` | Wait before a failed event is tried again, in seconds. | `300` | No |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | Dispatch attempts before an event is marked invalid. | `10` | No |
| `OUTBOX_PROCESSING_TIMEOUT_SEC` | Time after which the relay takes back an event stuck in processing, in seconds. | `600` | No |
| `OUTBOX_MAX_FAILED_PER_BATCH` | Failed events that each cycle takes back for a retry. | `25` | No |
| `OUTBOX_PRIORITY_EVENT_TYPES` | Comma-separated event types that each cycle takes first. | — | No |
| `OUTBOX_TABLE_NAME` | Outbox table name. | `outbox_events` | No |
| `RABBITMQ_ENABLED` | Open a RabbitMQ connection that only the readiness check uses. TED Lerian publishes no event through it. | `false` | No |
| `RABBITMQ_URL`, `RABBITMQ_HOST`, `RABBITMQ_PORT_AMQP`, `RABBITMQ_PORT_HOST`, `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`, `RABBITMQ_VHOST`, `RABBITMQ_QUEUE` | RabbitMQ connection. `RABBITMQ_URL` or `RABBITMQ_HOST` is required when RabbitMQ is enabled. | `RABBITMQ_HOST`: `localhost` | If RabbitMQ is enabled |
| `RABBITMQ_HEALTH_CHECK_URL`, `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS`, `RABBITMQ_REQUIRE_HEALTH_ALLOWED_HOSTS`, `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK`, `RABBITMQ_ALLOW_INSECURE_TLS` | RabbitMQ health check and TLS settings. | — | No |

## Telemetry

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Export OpenTelemetry traces and metrics. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector address. | `localhost:4317` | No |
| `OTEL_RESOURCE_SERVICE_NAME` | Service name on the telemetry. | `plugin-br-ted-lerian` | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Environment name on the telemetry. | `development` | No |
| `OTEL_LIBRARY_NAME` | Instrumentation library name. | Service default | No |
| `OTEL_TRUST_INBOUND_TRACE_CONTEXT` | Continue the trace that a caller sends in its request headers. | `false` | No |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.