> ## 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
> Variables de entorno de despliegue de Lerian STA: entorno objetivo del BACEN, almacenamiento S3, claves maestras de cifrado de sobre y trust store.
Lerian STA es el rail propiedad de Lerian que transmite y recibe archivos con el hub STA de BACEN. Defines estas variables en el momento del despliegue. Un reinicio del servicio hace que surtan efecto. Cada servicio Go de Lerian comparte un backbone universal: servidor, almacenes de datos, multi-tenancy, telemetría, autenticación de plugins y licenciamiento. La [referencia de configuración BYOC](/es/reference/byoc-configuration) documenta ese backbone una sola vez. Esta página cubre solo las variables distintivas de Lerian STA.
En las tablas siguientes, la columna **Valor por defecto / Requerida** muestra el valor por defecto. Un calificador en negrita marca una variable que debes definir, como **Requerida** o **Requerida en producción**. `—` significa que no hay valor por defecto. Una variable marcada como **Sensible** contiene material de credenciales o claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. Nunca guardes un valor en el repositorio.
## Servicio y runtime
| Variable | Valor por defecto / Requerida | Descripción |
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SERVER_ADDRESS` | — | Dirección de escucha HTTP principal. Defínela explícitamente: la etiqueta `envDefault` `:4028` no se materializa en runtime. Las sondas de liveness, readiness, métricas y versión se enlazan a este mismo puerto. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita la API de administración de configuración en tiempo de ejecución de [Systemplane](/es/reference/systemplane/overview) bajo el prefijo `/system` en el puerto principal. Desactivada por defecto (modo solo variables de entorno). |
| `DEFAULT_TENANT_ID` | — | UUID opcional usado solo como fallback de `ce-tenantid` de streaming/outbox cuando un evento no tiene ID de tenant; no se inyecta en el contexto ordinario de solicitudes o transferencias single-tenant. |
| `BACEN_ENVIRONMENT` | `homologation` | Selecciona el objetivo STA de BACEN upstream para la sonda de conectividad: `homologation` (staging) o `production` (en vivo). Un valor no reconocido recae en `homologation`, de modo que un stack no productivo no pueda enrutar tráfico al servicio de BACEN en vivo. |
Lerian STA expone `/health` (liveness) y `/readyz` (readiness) en el puerto principal, además de `/version` y `/metrics`. Cuando habilitas la multi-tenancy, también expone `GET /readyz/tenant/{id}`. Consulta [Salud y readiness](/es/reference/health-and-readiness) para el contrato de las sondas.
## Almacenamiento de objetos
Lerian STA persiste los bytes de transferencia y las descargas entrantes en un almacén de objetos compatible con S3. Cada subsistema configura su propia conexión a través del AWS SDK, de modo que el mismo cableado sirve para AWS S3, MinIO o un almacén local.
| Variable | Valor por defecto / Requerida | Descripción |
| -------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Requerida en producción** | Bucket que contiene ambas direcciones de transferencia, indexado por prefijo de dirección. El arranque de producción se rechaza si está vacío, independientemente de que las transferencias entrantes estén habilitadas. |
| `TRANSFER_INBOUND_ENABLED` | `false` | Habilita la pipeline de transferencia entrante (extraída por BACEN). No cambia el requisito del bucket en producción porque las transferencias salientes también lo usan. |
| `TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES` | `0` | Un valor de `0` significa que no hay techo para el tamaño de archivo entrante anunciado por BACEN. Define un valor positivo para omitir archivos mayores antes de escribir byte alguno. |
| `AWS_REGION` | — | Región para AWS Secrets Manager M2M y, cuando `MASTER_KEY_KMS_REGION` está vacío, el fallback de AWS KMS. No configura el almacenamiento de objetos. |
| `AWS_ACCESS_KEY_ID` | — | Clave de acceso para el almacén de objetos. Sensible. Déjala sin definir cuando un rol IAM adjunto aporte las credenciales. |
| `AWS_SECRET_ACCESS_KEY` | — | Clave secreta para el almacén de objetos. Sensible. Déjala sin definir cuando un rol IAM adjunto aporte las credenciales. |
## Cifrado de sobre
Lerian STA protege las credenciales de operador con cifrado de sobre AES-GCM. El proceso del manager siempre necesita el material de clave maestra. Un valor faltante o malformado aborta el arranque.
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MASTER_KEY_PROVIDER` | `envvar` | Origen de la clave de cifrado de sobre: `envvar` (clave leída de `MASTER_KEYS`) o `aws-kms` (clave envuelta por un KMS en la nube). |
| `MASTER_KEY_VERSION` | **Requerida** | Selecciona la versión de clave maestra actualmente activa. Debe coincidir con una versión presente en `MASTER_KEYS`. |
| `MASTER_KEYS` | **Requerida** | Pares `version:key` separados por comas. Sensible. Con `envvar`, cada valor es una clave AES-256 de 64 caracteres hex: `version:<64-hex-key>`. Con `aws-kms`, cada valor es texto cifrado de KMS en base64: `version:`, que se descifra en el proceso. Obtenla de tu gestor de secretos: un valor faltante o malformado aborta el arranque. |
| `MASTER_KEY_KMS_KEY_ID` | **Requerida si `aws-kms`** | Identificador de la clave AWS KMS usada para descifrar el texto cifrado de `MASTER_KEYS`. Con `aws-kms`, el texto cifrado se descifra en el proceso de STA. |
| `CREDENTIALS_RECOVERY_ON_BOOT` | `false` | Establécela explícitamente en `true` para ejecutar una vez al arrancar el barrido de recuperación de credenciales del lado worker dejadas a mitad de rotación por un proceso anterior. |
## Trust store
Cada tenant sube los certificados raíz X.509 que Lerian STA usa para validar el certificado TLS del servidor de BACEN. STA se autentica ante BACEN con credenciales de operador HTTP Basic y no adjunta certificado de cliente. El módulo de trust store siempre está activado. Lerian STA persiste los cuerpos PEM de los certificados en el almacén de objetos, por lo que necesita la conexión al bucket del trust store.
| Variable | Valor por defecto / Requerida | Descripción |
| --------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `TRUST_STORE_S3_BUCKET` | **Requerida** | Bucket que contiene los PEM de certificados del trust store por tenant. El arranque falla sin él. |
| `TRUST_STORE_S3_REGION` | `us-east-1` | Región para el bucket del trust store. |
| `TRUST_STORE_S3_ENDPOINT` | — | Endpoint del almacén de objetos. Déjalo vacío para recaer en el endpoint por defecto de AWS S3. |
| `TRUST_STORE_S3_PATH_STYLE` | `false` | Usa el direccionamiento path-style. Requerido para MinIO o un almacén local; déjalo en `false` para AWS S3. |
| `TRUST_STORE_MAX_CERT_SIZE_BYTES` | `65536` | Tamaño máximo aceptado de un PEM de certificado subido. |
| `TRUST_STORE_EXPIRING_SOON_DAYS` | `30` | Ventana, en días, a partir de la cual se reporta un certificado como próximo a expirar. Ajustable por el operador con recarga en caliente. |
| `TRUST_STORE_DEFAULT_PAGE_SIZE` | `25` | Tamaño de página por defecto para la API de listado del trust store. |
| `TRUST_STORE_MAX_PAGE_SIZE` | `100` | Tamaño de página máximo para la API de listado del trust store. |
Lerian STA ejecuta su pipeline de auditoría en un worker dedicado. El publicador, el consumidor y el generador de exportación soportan modos single-tenant y multitenant; el generador también necesita su bucket S3. El gestor de particiones, la limpieza y el verificador requieren multi-tenancy. Configura explícitamente las flags de habilitación y los parámetros requeridos mediante las familias `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_CLEANUP_*`, `AUDIT_VERIFIER_*`, `AUDIT_EXPORT_GENERATOR_*` y `AUDIT_EXPORT_RATE_LIMIT_*`: las etiquetas `envDefault` no se materializan en general.