> ## 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](/en/rails/sisbajud/sisbajud-environment-variables) lists the variables of the Mensageria. [BYOC configuration essentials](/en/reference/byoc-configuration) 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](/en/reference/platform/systemplane/overview) 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`.
</Note>

## 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](/en/platform/licensing/license-manager) 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. |
| `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. |
| `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. |

## Mensageria connection

The executor calls the execution API of the Mensageria. [Integrating with Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-integration#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. The executor answers a probe only when the tenant of the delivery is this value. |

## 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](/en/rails/sisbajud/sisbajud-executor-operations#institution-setup) describes it.

## Event streaming

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publish events. With HashiCorp Vault, 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. |

<h2 id="values-that-must-match-the-mensageria">
  Values that must match the Mensageria
</h2>

* **`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.** On the Mensageria, the M2M client in `MENSAGERIA_CLIENT_ID` holds the role `br-sisbajud-executor-role`. `EXECUTOR_M2M_SUBJECT` is the `sub` of the token of that client.


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