> ## 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.
# Environment variables
> Deploy-time environment variables for Lerian STA: the BACEN environment target, S3-compatible object storage, envelope-encryption master keys, and trust store.
Lerian STA is the Lerian-owned rail that transmits and receives files with the BACEN STA hub. You set these variables at deploy time. A service restart makes them take effect. Every Lerian Go service shares a universal backbone — server, datastores, multi-tenancy, telemetry, plugin authentication, and licensing. [BYOC configuration essentials](/en/reference/byoc-configuration) documents that backbone once. This page covers only the variables distinctive to Lerian STA.
In the tables below, the **Default / Required** column shows the default value. A bold qualifier marks a variable you must set, such as **Required** or **Required in production**. `—` means no default. A variable flagged **Sensitive** carries credential or key material. Inject it from your secret manager at deploy time. Never commit a value.
## Service and runtime
| Variable | Default / Required | Description |
| --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_ADDRESS` | — | Main HTTP listen address. Set it explicitly: the `:4028` `envDefault` tag is not materialized at runtime. The liveness, readiness, metrics, and version probes bind this same port. |
| `SYSTEMPLANE_ENABLED` | `false` | Enable the [Systemplane](/en/reference/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode). |
| `DEFAULT_TENANT_ID` | — | Optional UUID fallback used only for the streaming/outbox `ce-tenantid` when an event has no tenant ID; it is not injected into ordinary single-tenant request or transfer context. |
| `BACEN_ENVIRONMENT` | `homologation` | Selects the upstream BACEN STA target for the connectivity probe: `homologation` (staging) or `production` (live). An unrecognized value falls back to `homologation` so a non-production stack cannot route traffic to the live BACEN service. |
Lerian STA exposes `/health` (liveness) and `/readyz` (readiness) on the main port, plus `/version` and `/metrics`. When you enable multi-tenancy, it also exposes `GET /readyz/tenant/{id}`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.
## Object storage
Lerian STA persists transfer bytes and inbound downloads to an S3-compatible object store. Each subsystem configures its own connection through the AWS SDK, so the same wiring drives AWS S3, MinIO, or a local store.
| Variable | Default / Required | Description |
| -------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Required in production** | Bucket holding both transfer directions, keyed by direction prefix. Production boot is refused if it is empty, regardless of whether inbound transfers are enabled. |
| `TRANSFER_INBOUND_ENABLED` | `false` | Enable the inbound (BACEN-pulled) transfer pipeline. It does not change the production bucket requirement because outbound transfers also use the bucket. |
| `TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES` | `0` | A value of `0` means no ceiling on BACEN-advertised inbound file size. Set a positive value to skip larger files before any bytes are written. |
| `AWS_REGION` | — | Region for M2M AWS Secrets Manager and, when `MASTER_KEY_KMS_REGION` is empty, the AWS KMS fallback. It does not configure object storage. |
| `AWS_ACCESS_KEY_ID` | — | Access key for the object store. Sensitive. Leave unset when an attached IAM role supplies credentials. |
| `AWS_SECRET_ACCESS_KEY` | — | Secret key for the object store. Sensitive. Leave unset when an attached IAM role supplies credentials. |
## Envelope encryption
Lerian STA protects operator credentials with AES-GCM envelope encryption. The manager process always needs the master-key material. A missing or malformed value aborts boot.
| Variable | Default / Required | Description |
| ------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MASTER_KEY_PROVIDER` | `envvar` | Source of the envelope-encryption key: `envvar` (key read from `MASTER_KEYS`) or `aws-kms` (key wrapped by a cloud KMS). |
| `MASTER_KEY_VERSION` | **Required** | Selects the currently active master-key version. Must match a version present in `MASTER_KEYS`. |
| `MASTER_KEYS` | **Required** | Comma-separated `version:key` pairs. Sensitive. With `envvar`, each value is a 64-hex-character AES-256 key: `version:<64-hex-key>`. With `aws-kms`, each value is base64 KMS ciphertext: `version:`, decrypted in process. Source from your secret manager — a missing or malformed value aborts boot. |
| `MASTER_KEY_KMS_KEY_ID` | **Required if `aws-kms`** | Identifier of the AWS KMS key used to decrypt the `MASTER_KEYS` ciphertext. With `aws-kms`, the ciphertext is decrypted in the STA process. |
| `CREDENTIALS_RECOVERY_ON_BOOT` | `false` | Set explicitly to `true` to run the worker-side credential-recovery sweep once at boot for credentials left mid-rotation by a previous process. |
## Trust store
Each tenant uploads the X.509 root certificates that Lerian STA uses to validate BACEN's server TLS certificate. STA authenticates to BACEN with HTTP Basic operator credentials and attaches no client certificate. The trust-store module is always on. Lerian STA persists certificate PEM bodies to the object store, so it needs the trust-store bucket connection.
| Variable | Default / Required | Description |
| --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| `TRUST_STORE_S3_BUCKET` | **Required** | Bucket holding the per-tenant trust-store certificate PEMs. Boot fails without it. |
| `TRUST_STORE_S3_REGION` | `us-east-1` | Region for the trust-store bucket. |
| `TRUST_STORE_S3_ENDPOINT` | — | Object-store endpoint. Leave empty to fall back to the AWS S3 default endpoint. |
| `TRUST_STORE_S3_PATH_STYLE` | `false` | Use path-style addressing. Required for MinIO or a local store; leave `false` for AWS S3. |
| `TRUST_STORE_MAX_CERT_SIZE_BYTES` | `65536` | Maximum accepted size of an uploaded certificate PEM. |
| `TRUST_STORE_EXPIRING_SOON_DAYS` | `30` | Window, in days, at which a certificate is reported as expiring soon. Operator-tunable with hot reload. |
| `TRUST_STORE_DEFAULT_PAGE_SIZE` | `25` | Default page size for the trust-store listing API. |
| `TRUST_STORE_MAX_PAGE_SIZE` | `100` | Maximum page size for the trust-store listing API. |
Lerian STA runs its audit pipeline in a dedicated worker. The publisher, consumer, and export generator support both single-tenant and multi-tenant modes; the export generator also needs its S3 bucket. The partition manager, cleanup, and verifier require multi-tenancy. Configure the enabled flags and required knobs explicitly through the `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_CLEANUP_*`, `AUDIT_VERIFIER_*`, `AUDIT_EXPORT_GENERATOR_*`, and `AUDIT_EXPORT_RATE_LIMIT_*` families: `envDefault` tags are not generally materialized.