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

# Variables de entorno de Lerian SISBAJUD executor

> Variables de entorno de Lerian SISBAJUD executor: runtime, autenticación, licencia, gestión de claves, conexión con la Mensageria, tiempos de ejecución, listener de webhook, Midaz y streaming de eventos.

Esta página lista las variables de entorno del **executor**. [Variables de entorno de la Lerian SISBAJUD Mensageria](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-environment-variables.md) lista las variables de la Mensageria. [Fundamentos de configuración de BYOC](https://docs.lerian.studio/es/reference/byoc-configuration.md) documenta las variables que comparte cada servicio Go de Lerian: servidor, almacenes de datos, telemetría y autenticación de plugins.

En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita (por ejemplo, **Obligatorio**) marca las variables que debes configurar. `—` significa que no hay valor predeterminado. Una variable marcada como **Sensible** guarda una credencial o material de claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. No hagas commit de su valor.

`MENSAGERIA_BASE_URL` activa el executor. Los requisitos del executor de abajo se aplican cuando está configurada.

## Servicio y runtime

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `SERVER_ADDRESS` | **Configúrala como `:4029`** | Dirección de escucha de la API principal. La imagen expone el puerto 4029. `/health`, `/readyz` y `/version` usan este puerto. |
| `ENVIRONMENT_NAME` | — | Entorno de ejecución. `local`, `development`, `staging`, `e2e` y `test` son valores de no producción. Cualquier otro valor, y ningún valor, ejecuta las verificaciones de producción. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc` o `saas`. Con `saas`, el arranque rechaza una conexión PostgreSQL o Redis sin TLS. Fuera de `local`, el listener de webhook necesita TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant de un despliegue single-tenant. Debe ser un UUID. |
| `SYSTEMPLANE_ENABLED` | `false` | Sirve la API de administración de [Systemplane](https://docs.lerian.studio/es/reference/platform/systemplane/overview.md) en `/system` y los documentos de rutas contables en `/tenant-system`. |

> [!NOTE]
>
> Las verificaciones de producción exigen `POSTGRES_PASSWORD` y rechazan `POSTGRES_SSLMODE=disable`. Con `STREAMING_ENABLED=true`, también exigen `STREAMING_TLS_ENABLED=true`.

## Autenticación

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` | Verifica los bearer tokens de la API principal con el Access Manager. Con `false`, el executor no sirve la rotación de la clave de credenciales. |
| `PLUGIN_AUTH_HOST` | **Obligatorio** | Dirección del Access Manager. El executor obtiene su token para la Mensageria en esta dirección, también cuando `PLUGIN_AUTH_ENABLED` es `false`. |

## Licencia

[License Manager](https://docs.lerian.studio/es/platform/licensing/license-manager.md) describe cómo el producto verifica la licencia.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `LICENSE_KEY` | **Obligatorio** | La clave de licencia que Lerian emitió para Lerian SISBAJUD. El arranque rechaza un valor vacío en cualquier entorno. |
| `ORGANIZATION_IDS` | **Obligatorio** | Alcance de la licencia. Configúrala como `global`. Cualquier otro valor rechaza el arranque. |

## Gestión de claves

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `KMS_PROVIDER` | **Obligatorio cuando `ENVIRONMENT_NAME` es `production`** | Gestor de claves: `vault` (HashiCorp Vault Transit) o `aws` (AWS KMS). Cualquier otro valor rechaza el arranque. Con cualquier otro entorno, un valor no configurado significa `vault`. |
| `AWS_REGION` | **Obligatorio con `aws`** | Región de AWS KMS. |
| `KMS_AWS_KEY_MODE` | **Obligatorio con `aws`** | `managed` o `provided`. No tiene valor predeterminado. Cualquier otro valor rechaza el arranque. |
| `KMS_AWS_KEY_ARN` | **Obligatorio con `provided`** | ARN de tu clave de AWS KMS para los datos de la institución, en la región de `AWS_REGION`. Un ARN de alias rechaza el arranque. Con `managed`, déjala vacía. |
| `KMS_AWS_CREDENTIALS_KEY_ARN` | **Obligatorio con `provided`** | ARN de tu clave de AWS KMS para las credenciales de conector almacenadas, con las mismas reglas. Debe ser una clave distinta de `KMS_AWS_KEY_ARN`. |
| `KMS_AWS_ROTATION_CHECK_INTERVAL_SEC` | `3600` | Con `provided`, el intervalo, en segundos, en el que el executor busca una rotación de tus claves. De `1` a `86400`. |
| `KMS_AWS_TIMEOUT_SEC` | `20` | Timeout de cada llamada a AWS KMS, en segundos. De `1` a `600`. |
| `VAULT_ADDR` | **Obligatorio con `vault`** | Dirección de tu Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` o `approle`. Cualquier otro valor rechaza el arranque. |
| `VAULT_TOKEN` | **Obligatorio para `token` cuando `ENVIRONMENT_NAME` es `production`** | Token de Vault. Sensible. |
| `VAULT_APPROLE_ROLE_ID` | **Obligatorio para `approle`** | Role ID de AppRole. Sensible. |
| `VAULT_APPROLE_SECRET_ID` | **Obligatorio para `approle`** | Secret ID de AppRole. Sensible. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Ruta de montaje del motor Transit. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout de cada solicitud a Vault, en segundos. De `1` a `600`. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renueva el token de Vault en segundo plano. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Tiempo mínimo entre dos renovaciones, en segundos. |

Con AWS KMS, los dos modos de clave son:

* **`managed`.** El executor crea dos claves para cada institución: una para sus datos y una para sus credenciales de conector almacenadas. `credential-kek:rotate` rota la clave de credenciales.
* **`provided`.** Tú creas las dos claves. El executor nunca las crea ni las rota, y `credential-kek:rotate` devuelve `422`. Cuando el custodio de tus claves rota una clave, el executor registra la nueva versión.

Los requisitos de la clave, las credenciales de AWS, los permisos, excepto `kms:ListAliases`, y el contexto de cifrado son los mismos que en la Mensageria. [AWS KMS en la Mensageria](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-environment-variables.md#aws-kms) los enumera. Elige el proveedor de claves una sola vez. Cuando la base de datos contiene datos que otro proveedor de claves protege, el arranque rechaza.

## Conexión con la Mensageria

El executor llama a la API de ejecución de la Mensageria. [Integración con Lerian SISBAJUD](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-integration.md#execution-api) la describe.

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `MENSAGERIA_BASE_URL` | **Obligatorio** | URL base de la API de ejecución de la Mensageria (`SISBAJUD_EXECUTION_ADDRESS` en la Mensageria). Debe ser una URL `https` con host. |
| `MENSAGERIA_MTLS_ENABLED` | `false` | `true` presenta un certificado de cliente. `false` usa TLS unidireccional. Cualquier otro valor rechaza el arranque. |
| `MENSAGERIA_TLS_CA_FILE` | **Obligatorio si `MENSAGERIA_MTLS_ENABLED=true`** | Paquete de CA que verifica la Mensageria. Con TLS unidireccional, es opcional, y un valor vacío usa el almacén de confianza del sistema. |
| `MENSAGERIA_TLS_CLIENT_CERT_FILE` | **Obligatorio si `MENSAGERIA_MTLS_ENABLED=true`** | Certificado de cliente del executor. |
| `MENSAGERIA_TLS_CLIENT_KEY_FILE` | **Obligatorio si `MENSAGERIA_MTLS_ENABLED=true`** | Clave privada de ese certificado. Sensible. |
| `EXECUTOR_M2M_SUBJECT` | **Obligatorio** | El `sub` del token M2M del executor. El executor lo registra como dueño de cada institución que crea. |
| `MENSAGERIA_CLIENT_ID` | **Obligatorio** | Client ID del cliente M2M del executor. |
| `MENSAGERIA_CLIENT_SECRET` | **Obligatorio** | Client secret de ese cliente. Sensible. El arranque rechaza un par con solo uno de los dos valores. |
| `STREAMING_HUB_TENANT_ID` | **Obligatorio** | Tenant de las sondas canario. |

## Tiempos de ejecución

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `EXECUTOR_TICK_EVERY` | `30s` | Intervalo del ciclo de ejecución. Duración Go mayor que 0. |
| `EXECUTOR_HEARTBEAT_EVERY` | **Obligatorio** | Intervalo de los heartbeats de una escritura cuyo resultado no se conoce. Duración Go mayor que 0. |
| `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` | `3` | Número de heartbeats sin cambio antes de que la orden pase a una decisión humana. |
| `RESPONSE_DEADLINE_MARGIN` | **Obligatorio** | Duración Go mayor que 0, por ejemplo `2h`. Antes del plazo de la orden, el executor mantiene este margen y entrega una escritura no resuelta a una decisión humana. |
| `EXECUTOR_SETTLE_WINDOW` | `1s` | Duración Go. Configúrala con al menos la latencia asíncrona de tu ledger. |
| `EXECUTOR_ORPHAN_RECONCILE_WINDOW` | `48h` | Hasta cuándo, en el pasado, el executor busca operaciones en cuentas de bloqueo que no escribió. |

## Listener de webhook

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `EXECUTOR_TRANSPORT` | `webhook` | Cómo llegan los avisos de ejecución al executor. Esta página describe `webhook`. |
| `EXECUTOR_HUB_WEBHOOK_ADDRESS` | `:9082` | Dirección de escucha del listener de webhook. |
| `EXECUTOR_HUB_WEBHOOK_PATH` | `/v1/webhooks/hub` | Ruta del listener de webhook. Debe empezar con `/`. |
| `EXECUTOR_HUB_WEBHOOK_SECRET` | **Obligatorio** | Secret de firma de la suscripción del Streaming Hub. Sensible. |
| `EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS` | — | El secret anterior a la última rotación. El listener acepta los dos secrets. Sensible. |
| `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC` | `300` | De `1` a `300`. El listener acepta una entrega fuera de esta diferencia de reloj, con una advertencia en el log. |
| `EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE` | **Obligatorio fuera de `DEPLOYMENT_MODE=local`, salvo que el TLS termine antes** | Certificado de servidor del listener. Configúralo junto con la clave. |
| `EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE` | **Obligatorio con el certificado** | Clave privada de ese certificado. Sensible. |
| `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED` | `false` | Configúrala como `true` cuando el TLS termina delante del listener. |
| `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS` | `5` | Número de intentos para cada entrega aceptada. Debe ser al menos 1 + `EXECUTOR_SETTLE_WINDOW` / `EXECUTOR_TICK_EVERY`, redondeado hacia arriba. |

## Midaz

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | Superficie de CRM de las instituciones que no definen `crmMode`: `legacy` (el CRM independiente de Midaz en `crmBaseUrl`) o `embedded` (el CRM del ledger Midaz en `baseUrl`). |

El executor lee la conexión con Midaz de cada institución desde su configuración, no desde variables de entorno. [Operar Lerian SISBAJUD executor](https://docs.lerian.studio/es/rails/sisbajud/sisbajud-executor-operations.md#institution-setup) la describe.

## Streaming de eventos

| Variable | Predeterminado / Obligatorio | Descripción |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publica eventos. Una rotación de la clave de credenciales publica `kek.rotated`. El arranque rechaza `false` cuando `STREAMING_BROKERS` está configurada. |
| `STREAMING_BROKERS` | — | Lista de brokers Kafka separada por comas. |
| `STREAMING_TLS_ENABLED` | **`true` en producción** | Se conecta a los brokers por TLS. |
| `OUTBOX_ENABLED` | `true` | Ruta de entrega duradera de los eventos. `STREAMING_ENABLED=true` la exige. |

## Valores que deben coincidir con la Mensageria

* **`RESPONSE_DEADLINE_MARGIN`.** La Mensageria lee la misma variable. Configura el mismo valor en los dos componentes.
* **TLS mutuo.** Configura `MENSAGERIA_MTLS_ENABLED` con el mismo valor que `SISBAJUD_EXECUTION_MTLS_ENABLED` en la Mensageria. Con TLS mutuo activo en la Mensageria e inactivo en el executor, el handshake TLS falla.
* **Identidad del executor.** `EXECUTOR_M2M_SUBJECT` es el `sub` del token del cliente M2M en `MENSAGERIA_CLIENT_ID`.


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