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

> Referencia de las variables de entorno que configuran Streaming Hub, agrupadas como las agrupa el código, con cada valor predeterminado y las verificaciones que el hub aplica al iniciar.

Esta referencia enumera las variables de entorno que configuran **Streaming Hub**. Lerian define estos valores cuando instala o actualiza el hub. Usa esta página para saber qué hace cada configuración, cuál es su valor predeterminado y qué verifica el hub al iniciar.

Cuando una variable obligatoria falta o no es válida, el hub no inicia. `STREAMING_HUB_ENV` selecciona el entorno. Los valores `staging` y `production` son entornos **reforzados**: rechazan los atajos locales que la columna **Obligatoria** marca como "Reforzado". Un valor de duración usa la sintaxis de Go, como `30s`, `5m` o `720h`. La unidad `d` no existe, así que escribe `2160h` para 90 días.

## Núcleo

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_ENV` | Entorno: `local`, `staging` o `production`. El hub rechaza cualquier otro valor y rechaza una variable definida pero en blanco. | `local` | No |
| `STREAMING_HUB_ROLE` | Parte del hub que ejecuta este proceso: `all`, `ingest` o `delivery`. Un valor desconocido registra una advertencia y ejecuta `all`. | `all` | No |
| `STREAMING_HUB_HTTP_LISTEN_ADDR` | Dirección de bind de la API HTTP. | `:8080` | No |
| `STREAMING_HUB_LOG_LEVEL` | Nivel de log. | `info` | No |
| `STREAMING_HUB_SHUTDOWN_TIMEOUT` | Tiempo que el hub permite para que termine el trabajo en curso cuando se detiene. Debe ser menor que `35s`, o el inicio falla. | `30s` | No |
| `STREAMING_HUB_PRE_STOP_DRAIN_TIMEOUT` | Tiempo que el hub espera después de declararse no listo y antes de detenerse. `0` deshabilita la espera. | `5s` | No |
| `STREAMING_HUB_SWAGGER_ENABLED` | Sirve la especificación OpenAPI y su página de documentación. | `false` | No |

## Base de datos

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_POSTGRES_DSN` | Cadena de conexión de PostgreSQL. Los entornos reforzados exigen un DSN que verifique el servidor: `sslmode=verify-full`, o `verify-ca` con `sslrootcert`. Se acepta un host de socket Unix. Sensible. | — | Sí |
| `STREAMING_HUB_ALLOW_INSECURE_DB_TLS` | Acepta un DSN que no verifica el servidor en un entorno reforzado. | `false` | No |
| `STREAMING_HUB_POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas. Debe ser mayor que `0`. Si no está definida, el valor predeterminado depende del rol. | `25` (`all`), `8` (`ingest`), `16` (`delivery`) | No |
| `STREAMING_HUB_POSTGRES_MAX_IDLE_CONNS` | Conexiones inactivas que se mantienen abiertas. Debe ser `0` o más. Si no está definida, el valor predeterminado depende del rol. | `12` (`all`), `4` (`ingest`), `10` (`delivery`) | No |
| `STREAMING_HUB_POSTGRES_CONN_MAX_LIFETIME` | Tiempo hasta que el hub reemplaza una conexión. | `30m` | No |

## Dispatcher

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_DISPATCH_WORKERS` | Workers de entrega. El hub limita el valor a las conexiones abiertas menos `4`, con un mínimo de `1`. | `8` | No |
| `STREAMING_HUB_DISPATCH_IDLE_INTERVAL_MS` | Milisegundos que un worker espera después de no encontrar ningún job. | `250` | No |
| `STREAMING_HUB_POISON_THRESHOLD` | Veces que el barrido de recuperación puede retomar un job después de una caída del worker, sin resultado de entrega, antes de que el hub envíe el job a dead-letter como poison. | `5` | No |

## Rate limit

El hub mide las lecturas por tenant en un almacenamiento de contadores Redis.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_REDIS_ADDRESS` | Dirección del almacenamiento de contadores. | — | Sí |
| `STREAMING_HUB_REDIS_PASSWORD` | Contraseña del almacenamiento de contadores. Sensible. | — | No |
| `STREAMING_HUB_REDIS_TLS` | Usa TLS en el almacenamiento de contadores. | `true` | Reforzado: `true` |
| `STREAMING_HUB_REDIS_CA_CERT` | Bundle de CA para esa conexión TLS, en PEM codificado en base64. | — | No |
| `RATE_LIMIT_ENABLED` | Habilita el rate limit. El hub se niega a iniciar sin `true`. | `false` | Sí: `true` |
| `ALLOW_RATELIMIT_FAIL_OPEN` | Comportamiento cuando el almacenamiento de contadores no está accesible. Con `true`, las lecturas siguen sin límite. Con `false`, las rutas limitadas responden `503`. | `false` | No |
| `ALLOW_INSECURE_TLS` | Deshabilita la exigencia de TLS en todos los clientes que la biblioteca compartida crea en este proceso. Sirve solo para trabajo local. | — | Reforzado: distinto de `true` |
| `RATE_LIMIT_REDIS_TIMEOUT_MS` | Milisegundos que puede tardar una actualización de contador antes de que la solicitud deje de esperar el almacenamiento. | `500` | No |
| `STREAMING_HUB_PULL_RATE` | Lecturas por segundo de cada tenant en `GET /v1/events`. | `100` | No |
| `STREAMING_HUB_DASHBOARD_RATE` | Solicitudes por minuto de cada tenant en las dos lecturas del dashboard. | `60` | No |
| `STREAMING_HUB_READ_RATE` | Solicitudes por minuto de cada tenant en las lecturas de la Console: suscripciones, endpoint, health, artefactos de configuración y catálogo. | `60` | No |

## Licencia

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `LICENSE_KEY` | Clave de licencia de Lerian. El hub la verifica al iniciar en todos los entornos. Sensible. | — | Sí |
| `ORGANIZATION_IDS` | Alcance de la licencia. El valor debe ser `global`. | — | Sí |
| `IS_DEVELOPMENT` | Con `true`, el hub verifica la licencia en el servidor de licencias de desarrollo. | — | `production`: distinto de `true` |

## Tenancy

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_TENANT_ID` | Tenant de un hub single-tenant. Letras, dígitos, `-` y `_`, con una letra o un dígito al inicio. Debe coincidir con el `ce-tenantid` que los productores ponen en sus eventos. El modo multi-tenant la ignora y registra una advertencia. | — | Modo single-tenant |
| `STREAMING_HUB_DELEGATED_SCOPE_CLAIM` | Nombre de la claim del token que lleva el ámbito delegado de un llamador. | `atua_por` | No |
| `STREAMING_HUB_DELEGATED_KIND_CLAIM` | Nombre de la claim del token que lleva el tipo de credencial de un llamador con ámbito. | `nature` | No |

## Dashboard y health

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_DASHBOARD_CURSOR_HMAC_KEY` | Clave que firma los cursores de página del dashboard. Base64 estándar de exactamente 32 bytes. Una clave nueva invalida los cursores en uso. Los entornos reforzados rechazan la clave de desarrollo publicada. Sensible. | — | Sí |
| `STREAMING_HUB_HEALTH_WINDOW` | Período más largo que mide la vista de health de la suscripción. | `720h` | No |

## Secretos

El hub cifra los secretos de firma de webhook que almacena con una clave de cifrado de claves (KEK).

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_KEK_SOURCE` | Origen de la KEK: `env` o `secretsmanager`. Con los dos valores, el hub lee la KEK de la variable que indica `STREAMING_HUB_KEK_REF`. Con `secretsmanager`, la capa de despliegue pone el secreto administrado en esa variable. | `env` | No |
| `STREAMING_HUB_KEK_REF` | Nombre de la variable que guarda la KEK. Esa variable no puede estar vacía, y la clave debe tener al menos 32 bytes. Los entornos reforzados rechazan la clave de desarrollo publicada. | — | Sí |

## Kafka

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_KAFKA_BROKERS` | Brokers de Kafka (CSV). | — | Sí |
| `STREAMING_HUB_KAFKA_SCRAM_MECHANISM` | Mecanismo SCRAM: `SCRAM-SHA-256` o `SCRAM-SHA-512`. Exige TLS. | — | No |
| `STREAMING_HUB_KAFKA_SCRAM_USERNAME` | Usuario SCRAM. | — | Con un mecanismo SCRAM |
| `STREAMING_HUB_KAFKA_SCRAM_PASSWORD` | Contraseña SCRAM. Sensible. | — | Con un mecanismo SCRAM |
| `STREAMING_HUB_KAFKA_TLS_ENABLED` | Usa TLS en Kafka. | `false` | No |
| `STREAMING_HUB_KAFKA_CA_CERT` | Certificado de la CA para el TLS de Kafka. | — | No |
| `STREAMING_HUB_ALLOW_INSECURE_KAFKA` | Permite Kafka sin cifrado. Una conexión sin TLS la necesita. | `false` | Reforzado: `false` |
| `STREAMING_HUB_DLQ_RETENTION` | Tiempo que el hub conserva una observación de dead-letter. | `168h` | No |
| `STREAMING_HUB_DLQ_PRUNE_INTERVAL` | Tiempo entre eliminaciones de las observaciones de dead-letter vencidas. `0` o menos deshabilita la eliminación. | `1h` | No |

## Telemetría

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_METRICS_ENABLED` | Habilita OpenTelemetry. | `true` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. Si está vacía, el hub no envía telemetría. | — | No |
| `OTEL_INSECURE_EXPORTER` | Envía la telemetría sin TLS. | `false` | No |
| `ALLOW_INSECURE_OTEL` | Permite un exportador sin cifrado cuando `STREAMING_HUB_ENV` es `production`. Sin ella, ese caso detiene el inicio. | — | No |

## Catálogo

Un hub single-tenant lee el catálogo de eventos de los productores en `STREAMING_HUB_MANIFEST_SOURCES`. Un hub multi-tenant encuentra sus productores a partir de las credenciales de cada tenant.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_MANIFEST_SOURCES` | URL base de los productores (CSV), como `scheme://host[:port]` sin ruta. El modo multi-tenant la rechaza. Una entrada no válida detiene el inicio. | — | No |
| `STREAMING_HUB_MANIFEST_CLIENT_ID` | Client ID que el hub usa para leer manifiestos protegidos. Defínelo junto con el secreto, o no definas ninguno de los dos. | — | No |
| `STREAMING_HUB_MANIFEST_CLIENT_SECRET` | Client secret de esas lecturas. Sensible. | — | No |
| `STREAMING_HUB_MANIFEST_REFRESH_INTERVAL` | Segundos entre actualizaciones del catálogo. | `300` | No |

## Verificador de temas

El verificador compara temas, suscripciones y el catálogo, e informa las diferencias en métricas y logs. No cambia nada.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_RECONCILER_ENABLED` | Ejecuta el verificador. | `true` | No |
| `STREAMING_HUB_RECONCILER_INTERVAL` | Segundos entre pasadas del verificador. | `300` | No |

## Particiones e historial

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_PARTITION_CRON_INTERVAL` | Tiempo entre las ejecuciones que crean particiones futuras. | `6h` | No |
| `STREAMING_HUB_PARTITION_FUTURE_BUFFER_WEEKS` | Particiones semanales que el hub mantiene listas por adelantado. Debe ser al menos `1`. | `4` | No |
| `STREAMING_HUB_PARTITION_RETENTION_ENABLED` | Elimina las particiones vencidas. Con `false`, el hub no elimina ninguna. | `false` | No |
| `STREAMING_HUB_PARTITION_RETENTION_HORIZON` | Edad a la que vence una partición. Con la retención habilitada, debe ser al menos las semanas de anticipación por siete días, y un valor no válido detiene el inicio. | `2160h` | No |
| `STREAMING_HUB_ARCHIVE_BUCKET` | Nombre del bucket S3 para el historial de entregas archivado. Usa el nombre solo. Si está vacía, el archivado está deshabilitado. Después de que una réplica inicia con un bucket, la retención elimina solo el historial que llegó al archivo. Limpiar la variable después no quita esa regla. | — | No |
| `STREAMING_HUB_HISTORY_RETENTION_ENABLED` | Mantiene un historial corto de entregas: el hub elimina los datos calientes después de archivarlos. Exige la retención de particiones y el bucket de archivo. Después de que el hub registra este modo, el modo es permanente. | `false` | No |

## Idempotencia

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_IDEMPOTENCY_TTL` | Tiempo que una respuesta confirmada sigue disponible para replay con la misma clave `X-Idempotency`. | `24h` | No |
| `STREAMING_HUB_IDEMPOTENCY_REAP_INTERVAL` | Tiempo entre eliminaciones de los registros de idempotencia vencidos. `0` o menos deshabilita la eliminación. | `5m` | No |

## Deshabilitación automática de endpoints

El hub deshabilita una suscripción cuando sus entregas fallan durante un período largo y espaciado. Una entrega exitosa reinicia el conteo.

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_AUTODISABLE_ENABLED` | Habilita la deshabilitación automática. | `true` | No |
| `STREAMING_HUB_AUTODISABLE_FAILURE_WINDOW` | Tiempo mínimo desde la primera falla. | `120h` | No |
| `STREAMING_HUB_AUTODISABLE_FAILURE_SPREAD` | Tiempo mínimo entre la primera y la última falla. | `12h` | No |

## Autenticación

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Habilita la autenticación de Access Manager. | `true` | Reforzado: `true` |
| `PLUGIN_AUTH_ADDRESS` | Dirección de Access Manager. | `http://localhost:4000` | No |
| `AUTH_REQUIRED` | Con `true`, las rutas protegidas responden `503` cuando la autenticación está deshabilitada o la dirección de Access Manager está vacía. | `false` | No |
| `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED` | Con `true` y la autenticación deshabilitada, las rutas protegidas siguen exigiendo un bearer token y responden `401` sin él. No llaman a Access Manager. Sin `AUTH_JWT_VERIFY_CERT` ni `AUTH_JWT_VERIFY_CERT_PATH`, el hub no verifica la firma del token. | `false` | No |
| `AUTH_M2M_INVERSION_ENABLED` | Con `true`, cada token de aplicación se autoriza con sus propios permisos. El hub responde entonces `401` a un token cuyo claim `type` no es `normal-user` ni `application`. Sin `true`, todo token que no es de usuario se autoriza bajo un único rol compartido. | `false` | No |
| `AUTH_M2M_PRODUCT_FORWARD_ENABLED` | Con `true` y `AUTH_M2M_INVERSION_ENABLED=true`, el hub también envía el nombre de su producto a Access Manager cuando verifica un token de aplicación. | `false` | No |
| `AUTH_TIMEOUT` | Tiempo límite de la verificación en Access Manager de una solicitud, con los reintentos incluidos. | `30s` | No |
| `AUTH_CACHE_TTL` | Tiempo que el hub guarda cada decisión de Access Manager. Un cambio de permisos puede tardar ese tiempo en aplicarse. Si no está definida, el hub no guarda ninguna decisión. | — | No |
| `AUTH_BREAKER_ENABLED` | Habilita un circuit breaker en las llamadas a Access Manager. Después de 5 llamadas fallidas seguidas, detiene las llamadas durante 30 segundos. Mientras tanto, el hub rechaza cada solicitud que no tiene una aprobación en caché. | `false` | No |
| `AUTH_RETRY_MAX` | Máximo de reintentos de una llamada a Access Manager que falla sin una decisión. `0` deshabilita los reintentos. | `0` | No |
| `AUTH_JWT_VERIFY_CERT` | Una o más claves públicas RSA o certificados X.509 en PEM, separados por saltos de línea. Con una clave cargada, el hub verifica la firma RS256 y la expiración de cada bearer token, y responde `401` cuando la verificación falla. Tiene precedencia sobre `AUTH_JWT_VERIFY_CERT_PATH`. | — | No |
| `AUTH_JWT_VERIFY_CERT_PATH` | Ruta de un archivo con el mismo contenido. El hub lo lee solo cuando `AUTH_JWT_VERIFY_CERT` está vacía. | — | No |
| `AUTH_JWT_ISSUER` | Con una clave cargada, el hub responde `401` a un token cuyo claim `iss` difiere de este valor. | — | No |
| `TRUSTED_PROXIES` | Rangos CIDR, separados por comas, de los proxies que se conectan directamente al hub. El hub resuelve la dirección de quien llama a través de ellos y la envía a Access Manager para la [lista de IP permitidas](https://docs.lerian.studio/es/platform/access-manager/features/ip-allowlist/deployment.md). Si no está definida, el hub no envía la dirección de quien llama. | — | No |
| `IDP_DECLARATION_ENABLED` | Publica la declaración de permisos del hub en el servicio de identidad al iniciar. Solo `true` la habilita. La publicación también necesita `PLUGIN_AUTH_ENABLED=true` definida en el entorno. También necesita la dirección de Access Manager definida en el entorno como `PLUGIN_AUTH_HOST`, o como `PLUGIN_AUTH_ADDRESS` cuando `PLUGIN_AUTH_HOST` está vacía. Cuando falla, el hub registra una advertencia y sigue atendiendo. | — | No |
| `IDP_HOST` | URL base del servicio de identidad para la declaración. | — | Con la declaración habilitada |
| `IDP_M2M_CLIENT_ID` | Client ID de la declaración. | — | Con la declaración habilitada |
| `IDP_M2M_CLIENT_SECRET` | Client secret de la declaración. Sensible. | — | Con la declaración habilitada |

## Modo multi-tenant

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `MULTI_TENANT_ENABLED` | Habilita el modo multi-tenant mediante Tenant Manager. | `false` | No |
| `ENV_NAME` | Nombre del entorno para Tenant Manager. El modo multi-tenant rechaza un valor vacío y `local`. | — | Modo multi-tenant |
| `MULTI_TENANT_URL` | URL de Tenant Manager. | — | Modo multi-tenant |
| `MULTI_TENANT_SERVICE_API_KEY` | Clave de API que el hub envía a Tenant Manager. Sensible. | — | Modo multi-tenant |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite una URL `http` para Tenant Manager. | `false` | No |
| `MULTI_TENANT_TIMEOUT` | Timeout, en segundos, de una llamada a Tenant Manager. `0` usa el valor predeterminado de la biblioteca. | `0` | No |
| `MULTI_TENANT_CACHE_TTL_SEC` | Segundos que el hub guarda en cache la configuración de un tenant. `0` usa el valor predeterminado de la biblioteca. | `0` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Llamadas fallidas a Tenant Manager antes de que se abra el circuit breaker. `0` deshabilita el breaker. | `0` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Segundos que el circuit breaker permanece abierto. `0` usa el valor predeterminado de la biblioteca. | `0` | No |
| `MULTI_TENANT_REDIS_HOST` | Host del Redis que transporta los eventos de ciclo de vida de los tenants. Si está vacía, el hub funciona sin ese listener. | — | No |
| `MULTI_TENANT_REDIS_PORT` | Puerto de ese Redis. | `6379` | No |
| `MULTI_TENANT_REDIS_PASSWORD` | Contraseña de ese Redis. Sensible. | — | No |
| `MULTI_TENANT_REDIS_TLS` | Usa TLS en ese Redis. | `false` | No |
| `MULTI_TENANT_REDIS_CA_CERT` | Certificado de la CA para esa conexión TLS. | — | No |
| `AWS_REGION` | Región de AWS, que lee el SDK de AWS. | — | No |

## Artefactos de configuración de AWS

| Variable | Descripción | Valor predeterminado | Obligatoria |
| - | - | - | - |
| `STREAMING_HUB_AWS_HUB_PRINCIPAL_ARN` | ARN del rol de AWS del hub. Tu rol de concesión delegada confía en él, y los artefactos de configuración lo ponen en la política de confianza. Si está vacía, el hub no genera artefactos de configuración de AWS. | — | No |
| `STREAMING_HUB_AWS_SETUP_TEMPLATE_URL` | URL pública de la plantilla de CloudFormation que crea el rol de concesión delegada. Si está vacía, el hub no genera artefactos de configuración de AWS. | — | No |


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