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

# Lerian SISBAJUD executor environment variables

> Environment variables of the Lerian SISBAJUD executor: runtime, authentication, license, key management, the Mensageria connection, execution timing, the webhook listener, Midaz, and event streaming.

This page lists the environment variables of the **executor**. [Lerian SISBAJUD Mensageria environment variables](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-environment-variables.md) lists the variables of the Mensageria. [BYOC configuration essentials](https://docs.lerian.studio/en/reference/byoc-configuration.md) documents the variables that every Lerian Go service shares: server, datastores, telemetry, and plugin authentication.

In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks the variables you must set. `—` means no default. A variable marked **Sensitive** holds a credential or key material. Inject it from your secret manager at deploy time. Do not commit its value.

`MENSAGERIA_BASE_URL` turns on the executor. The executor requirements below apply when it is set.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_ADDRESS` | **Set it to `:4029`** | Listen address of the main API. The image exposes port 4029. `/health`, `/readyz`, and `/version` use this port. |
| `ENVIRONMENT_NAME` | — | Runtime environment. `local`, `development`, `staging`, `e2e`, and `test` are non-production values. Any other value, and no value, runs the production checks. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc`, or `saas`. With `saas`, the boot refuses a PostgreSQL or Redis connection without TLS. Outside `local`, the webhook listener needs TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant of a single-tenant deployment. It must be a UUID. |
| `SYSTEMPLANE_ENABLED` | `false` | Serve the [Systemplane](https://docs.lerian.studio/en/reference/platform/systemplane/overview.md) admin API under `/system`, and the accounting-route documents under `/tenant-system`. |

> [!NOTE]
>
> The production checks require `POSTGRES_PASSWORD` and refuse `POSTGRES_SSLMODE=disable`. With `STREAMING_ENABLED=true`, they also require `STREAMING_TLS_ENABLED=true`.

## Authentication

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` | Check bearer tokens on the main API with the Access Manager. With `false`, the executor does not serve the credential key rotation. |
| `PLUGIN_AUTH_HOST` | **Required** | Address of the Access Manager. The executor gets its token for the Mensageria from this address, also when `PLUGIN_AUTH_ENABLED` is `false`. |

## License

[License Manager](https://docs.lerian.studio/en/platform/licensing/license-manager.md) describes how the product checks the license.

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | The license key that Lerian issued for Lerian SISBAJUD. The boot refuses an empty value in every environment. |
| `ORGANIZATION_IDS` | **Required** | License scope. Set it to `global`. Any other value refuses the boot. |

## Key management

| Variable | Default / Required | Description |
| - | - | - |
| `KMS_PROVIDER` | **Required when `ENVIRONMENT_NAME` is `production`** | Key manager: `vault` (HashiCorp Vault Transit) or `aws` (AWS KMS). Any other value refuses the boot. With any other environment, an unset value means `vault`. |
| `AWS_REGION` | **Required with `aws`** | Region of AWS KMS. |
| `KMS_AWS_KEY_MODE` | **Required with `aws`** | `managed` or `provided`. It has no default. Any other value refuses the boot. |
| `KMS_AWS_KEY_ARN` | **Required with `provided`** | ARN of your AWS KMS key for the institution data, in the region of `AWS_REGION`. An alias ARN refuses the boot. With `managed`, leave it empty. |
| `KMS_AWS_CREDENTIALS_KEY_ARN` | **Required with `provided`** | ARN of your AWS KMS key for the stored connector credentials, with the same rules. It must be a different key from `KMS_AWS_KEY_ARN`. |
| `KMS_AWS_ROTATION_CHECK_INTERVAL_SEC` | `3600` | With `provided`, the interval, in seconds, at which the executor looks for a rotation of your keys. From `1` to `86400`. |
| `KMS_AWS_TIMEOUT_SEC` | `20` | Timeout of each AWS KMS call, in seconds. From `1` to `600`. |
| `VAULT_ADDR` | **Required with `vault`** | Address of your Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` or `approle`. Any other value refuses the boot. |
| `VAULT_TOKEN` | **Required for `token` when `ENVIRONMENT_NAME` is `production`** | Vault token. Sensitive. |
| `VAULT_APPROLE_ROLE_ID` | **Required for `approle`** | AppRole role ID. Sensitive. |
| `VAULT_APPROLE_SECRET_ID` | **Required for `approle`** | AppRole secret ID. Sensitive. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Mount path of the Transit engine. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout of each Vault request, in seconds. From `1` to `600`. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renew the Vault token in the background. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Minimum time between two renewals, in seconds. |

With AWS KMS, the two key modes are:

* **`managed`.** The executor creates two keys for each institution: one for its data and one for its stored connector credentials. `credential-kek:rotate` rotates the credentials key.
* **`provided`.** You create the two keys. The executor never creates or rotates them, and `credential-kek:rotate` returns `422`. When your key custodian rotates a key, the executor records the new version.

The key requirements, the AWS credentials, the permissions except `kms:ListAliases`, and the encryption context are the same as on the Mensageria. [AWS KMS on the Mensageria](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-environment-variables.md#aws-kms) lists them. Choose the key provider once. When the database holds data that another key provider protects, the boot refuses.

## Mensageria connection

The executor calls the execution API of the Mensageria. [Integrating with Lerian SISBAJUD](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-integration.md#execution-api) describes it.

| Variable | Default / Required | Description |
| - | - | - |
| `MENSAGERIA_BASE_URL` | **Required** | Base URL of the execution API of the Mensageria (`SISBAJUD_EXECUTION_ADDRESS` on the Mensageria). It must be an `https` URL with a host. |
| `MENSAGERIA_MTLS_ENABLED` | `false` | `true` presents a client certificate. `false` uses one-way TLS. Any other value refuses the boot. |
| `MENSAGERIA_TLS_CA_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | CA bundle that verifies the Mensageria. With one-way TLS, it is optional, and an empty value uses the system trust store. |
| `MENSAGERIA_TLS_CLIENT_CERT_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | Client certificate of the executor. |
| `MENSAGERIA_TLS_CLIENT_KEY_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | Private key of that certificate. Sensitive. |
| `EXECUTOR_M2M_SUBJECT` | **Required** | The `sub` of the M2M token of the executor. The executor records it as the owner of each institution that it creates. |
| `MENSAGERIA_CLIENT_ID` | **Required** | Client ID of the M2M client of the executor. |
| `MENSAGERIA_CLIENT_SECRET` | **Required** | Client secret of that client. Sensitive. The boot refuses a pair with only one of the two values. |
| `STREAMING_HUB_TENANT_ID` | **Required** | Tenant of the canary probes. |

## Execution timing

| Variable | Default / Required | Description |
| - | - | - |
| `EXECUTOR_TICK_EVERY` | `30s` | Interval of the execution cycle. Go duration greater than 0. |
| `EXECUTOR_HEARTBEAT_EVERY` | **Required** | Interval of the heartbeats for a write whose outcome is not known. Go duration greater than 0. |
| `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` | `3` | Number of heartbeats without a change before the order goes to a human decision. |
| `RESPONSE_DEADLINE_MARGIN` | **Required** | Go duration greater than 0, for example `2h`. Before the order deadline, the executor keeps this margin and hands an unresolved write to a human decision. |
| `EXECUTOR_SETTLE_WINDOW` | `1s` | Go duration. Set it to at least the asynchronous latency of your ledger. |
| `EXECUTOR_ORPHAN_RECONCILE_WINDOW` | `48h` | How far back the executor looks for operations on block accounts that it did not write. |

## Webhook listener

| Variable | Default / Required | Description |
| - | - | - |
| `EXECUTOR_TRANSPORT` | `webhook` | How the execution notices reach the executor. This page describes `webhook`. |
| `EXECUTOR_HUB_WEBHOOK_ADDRESS` | `:9082` | Listen address of the webhook listener. |
| `EXECUTOR_HUB_WEBHOOK_PATH` | `/v1/webhooks/hub` | Route of the webhook listener. It must start with `/`. |
| `EXECUTOR_HUB_WEBHOOK_SECRET` | **Required** | Signing secret of the Streaming Hub subscription. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS` | — | The secret before the last rotation. The listener accepts both secrets. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC` | `300` | From `1` to `300`. The listener accepts a delivery outside this clock skew, with a warning in the log. |
| `EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE` | **Required outside `DEPLOYMENT_MODE=local`, unless TLS is terminated upstream** | Server certificate of the listener. Set it together with the key. |
| `EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE` | **Required with the certificate** | Private key of that certificate. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED` | `false` | Set it to `true` when TLS is terminated in front of the listener. |
| `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS` | `5` | Number of attempts for each accepted delivery. It must be at least 1 + `EXECUTOR_SETTLE_WINDOW` / `EXECUTOR_TICK_EVERY`, rounded up. |

## Midaz

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | CRM surface of the institutions that set no `crmMode`: `legacy` (the standalone Midaz CRM at `crmBaseUrl`) or `embedded` (the CRM of the Midaz ledger at `baseUrl`). |

The executor reads the Midaz connection of each institution from its configuration, not from environment variables. [Operating the Lerian SISBAJUD executor](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-executor-operations.md#institution-setup) describes it.

## Event streaming

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publish events. A credential key rotation publishes `kek.rotated`. The boot refuses `false` when `STREAMING_BROKERS` is set. |
| `STREAMING_BROKERS` | — | Comma-separated list of Kafka brokers. |
| `STREAMING_TLS_ENABLED` | **`true` in production** | Connect to the brokers over TLS. |
| `OUTBOX_ENABLED` | `true` | Durable delivery path of events. `STREAMING_ENABLED=true` requires it. |

## Values that must match the Mensageria

* **`RESPONSE_DEADLINE_MARGIN`.** The Mensageria reads the same variable. Set the same value on both components.
* **Mutual TLS.** Set `MENSAGERIA_MTLS_ENABLED` to the same value as `SISBAJUD_EXECUTION_MTLS_ENABLED` on the Mensageria. With mutual TLS on the Mensageria and off on the executor, the TLS handshake fails.
* **Executor identity.** `EXECUTOR_M2M_SUBJECT` is the `sub` of the token of the M2M client in `MENSAGERIA_CLIENT_ID`.


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