> ## 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.
# Configuración de Fetcher
> Las variables de entorno que definen un despliegue de Fetcher — cifrado, MongoDB, RabbitMQ, almacenamiento de objetos, multi-tenancy, telemetría y datasources internos.
Fetcher se configura por completo desde el entorno. Cada servicio lee su propio conjunto. El Manager y el Worker comparten la mayoría de las variables, y cada uno tiene algunas propias.
Para trabajo local, `make set-env` copia el `.env.example` de cada componente a `.env`. En producción, define las variables a través de tu orquestador.
**Los dos servicios necesitan el mismo `APP_ENC_KEY`.** El Worker lo usa para descifrar credenciales de datasource y para verificar la firma de cada mensaje que envía el Manager. Una clave ausente o corta detiene el proceso al arrancar. El log dice `master key too short: got 0 bytes, minimum 32 required`, y el servicio nunca abre un puerto.
## Ambos servicios
***
### Aplicación
| Variable | Descripción | Por defecto | Obligatoria |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `APP_ENC_KEY` | Clave maestra de 32 bytes codificada en base64. Genérala con `make generate-master-key`. Fetcher deriva de ella cuatro claves independientes. | — | Sí |
| `APP_ENC_KEY_VERSION` | Versión de clave registrada en cada credencial que Fetcher cifra. Increméntala cuando cambies la clave maestra. | `1` | No |
| `ENV_NAME` | Etiqueta del entorno. También selecciona el perfil del logger: `production`, `staging`, `uat`, `development` o `local`. Un valor ausente o desconocido selecciona el perfil `local`. El ejemplo que se distribuye define `development`. | — | No |
| `LOG_LEVEL` | Verbosidad del log. Si no la defines, sigue el perfil del entorno: `debug` para `local` y `development`, `info` para el resto. | — | No |
| `VERSION` | Cadena de versión que reporta `/version`. El ejemplo que se distribuye define `v1.0.0`. | `0.0.0` | No |
| `DEPLOYMENT_MODE` | `saas`, `byoc` o `local`. Etiqueta la respuesta de `/readyz` y activa la exigencia de TLS en SaaS. `local` además relaja la validación de licencia. | `local` | No |
| `ALLOW_INSECURE_TLS` | Permite conexiones en texto plano a MongoDB, Redis, PostgreSQL y RabbitMQ. Déjala sin definir en producción. | sin definir | No |
| `READYZ_DRAIN_DELAY_SEC` | Ventana de drenaje tras `SIGTERM`, en segundos. Mínimo `1`. | `12` | No |
### MongoDB
MongoDB guarda los metadatos propios de Fetcher: registros de conexión y registros de job.
| Variable | Descripción | Por defecto | Obligatoria |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `MONGO_URI` | Esquema de conexión: `mongodb` o `mongodb+srv`. Fetcher compone la URI de conexión a partir de él. El ejemplo que se distribuye define `mongodb`. | — | Sí |
| `MONGO_HOST` | Host de MongoDB. | — | Sí |
| `MONGO_PORT` | Puerto de MongoDB. | — | Sí |
| `MONGO_NAME` | Nombre de la base de datos MongoDB. El acceso de repositorio resuelve este nombre en minúsculas. | — | Sí |
| `MONGO_USER` | Usuario de la base de datos. | — | Sí |
| `MONGO_PASSWORD` | Contraseña de la base de datos. Fetcher la escapa para la URL. | — | Sí |
| `MONGO_PARAMETERS` | Parámetros extra de query-string para la URI. | — | No |
| `MONGO_TLS_CA_CERT` | Certificado CA en PEM codificado en base64 para TLS. | — | No |
### RabbitMQ
| Variable | Descripción | Por defecto | Obligatoria |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `RABBITMQ_URI` | Esquema AMQP. Fetcher compone la URL del broker a partir de él. El ejemplo que se distribuye define `amqp`. | — | Sí |
| `RABBITMQ_HOST` | Host del broker. | — | Sí |
| `RABBITMQ_PORT_AMQP` | Puerto AMQP. | — | Sí |
| `RABBITMQ_PORT_HOST` | Puerto de gestión. | — | No |
| `RABBITMQ_DEFAULT_USER` | Usuario del broker. | — | Sí |
| `RABBITMQ_DEFAULT_PASS` | Contraseña del broker. | — | Sí |
| `RABBITMQ_HEALTH_CHECK_URL` | URL de gestión que llama la sonda de readiness. El ejemplo que se distribuye la construye con `RABBITMQ_HOST` y `RABBITMQ_PORT_HOST`. | — | No |
| `RABBITMQ_FETCHER_WORK_QUEUE` | Cola que lleva los jobs de extracción del Manager al Worker. Los dos servicios deben nombrar la misma cola. El ejemplo que se distribuye usa `fetcher.extract-external-data.queue`. | — | Sí |
| `RABBITMQ_TLS` | Activa TLS hacia el broker. | `false` | No |
### Multi-tenancy
| Variable | Descripción | Por defecto | Obligatoria |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------- |
| `MULTI_TENANT_ENABLED` | Activa el aislamiento de una base de datos por tenant. También activa la guarda de seguridad sobre los hosts de datasource provistos por el tenant. | `false` | No |
| `MULTI_TENANT_URL` | URL del servicio Tenant Manager. | — | Con multi-tenancy |
| `MULTI_TENANT_SERVICE_API_KEY` | API key por defecto para las consultas al Tenant Manager. | — | Con multi-tenancy |
| `MULTI_TENANT_SERVICE_API_KEY_` | Clave por servicio. El sufijo es el nombre del servicio en mayúsculas, con los guiones convertidos en guiones bajos (`plugin-crm` pasa a `PLUGIN_CRM`). Si falta, usa la clave por defecto. | — | No |
| `MULTI_TENANT_REDIS_HOST` | Host de Redis para el Pub/Sub de tenants. | — | Con multi-tenancy |
| `MULTI_TENANT_REDIS_PORT` | Puerto de Redis del Pub/Sub de tenants. | `6379` | No |
| `MULTI_TENANT_REDIS_PASSWORD` | Contraseña de Redis del Pub/Sub de tenants. | — | No |
| `MULTI_TENANT_REDIS_TLS` | TLS para el Redis del Pub/Sub de tenants. El cliente confía en el almacén de certificados del runtime, así que instala ahí tu CA privada. | `false` | No |
| `MULTI_TENANT_MAX_TENANT_POOLS` | Techo de pools de conexión concurrentes por tenant. | `100` | No |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Timeout de inactividad antes de liberar el pool de un tenant. | `300` | No |
| `MULTI_TENANT_CACHE_TTL_SEC` | TTL de la configuración de tenant en caché. El ejemplo que se distribuye define `120`. | — | No |
| `MULTI_TENANT_TIMEOUT` | Timeout de las llamadas al Tenant Manager, en segundos. | `30` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Fallos consecutivos antes de que abra el circuit breaker de tenants. | `5` | No |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Cuánto permanece abierto el breaker antes de un intento de reinicio. | `30` | No |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite HTTP en texto plano hacia el Tenant Manager. | `false` | No |
**Paradas de arranque en modo multi-tenant.** `MULTI_TENANT_ENABLED=true` exige `MULTI_TENANT_URL`, `MULTI_TENANT_SERVICE_API_KEY` y `MULTI_TENANT_REDIS_HOST`. Un valor ausente aborta el arranque en ambos servicios, y el error nombra la variable. Dos variables `MULTI_TENANT_SERVICE_API_KEY_` que se normalizan al mismo token también abortan el arranque, y el error nombra el token. La credencial de un servicio nunca sobrescribe en silencio la de otro.
### Telemetría
| Variable | Descripción | Por defecto | Obligatoria |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------- |
| `ENABLE_TELEMETRY` | Activa trazas y métricas de OpenTelemetry. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. | — | Con telemetría |
| `OTEL_INSECURE_EXPORTER` | Permite una conexión del exportador en texto plano. | `false` | No |
| `OTEL_RESOURCE_SERVICE_NAME` | Nombre del servicio en la telemetría. Los ejemplos que se distribuyen definen `fetcher` para el Manager y `fetcher-worker` para el Worker. | — | No |
| `OTEL_LIBRARY_NAME` | Nombre de la librería de instrumentación. El ejemplo que se distribuye define `github.com/LerianStudio/fetcher/v2`. | — | No |
| `OTEL_RESOURCE_SERVICE_VERSION` | Atributo de versión del servicio. `/readyz` reporta este valor, y reporta `unknown` cuando está sin definir. El ejemplo que se distribuye lo apunta a `VERSION`. | — | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Atributo de entorno de despliegue. El ejemplo que se distribuye lo apunta a `ENV_NAME`. | — | No |
## Solo el Manager
***
| Variable | Descripción | Por defecto | Obligatoria |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------- |
| `SERVER_ADDRESS` | Dirección de escucha de la API HTTP. El mismo listener sirve `/health`, `/readyz`, `/metrics` y `/version`. El ejemplo que se distribuye la construye a partir de `SERVER_PORT`, que define en `4006`. | — | Sí |
| `SWAGGER_ENABLED` | Sirve la referencia de API en `/swagger/docs` y el contrato OpenAPI 3.1 en `/swagger/openapi.json` y `/swagger/openapi.yaml`. | `false` | No |
| `PLUGIN_AUTH_ENABLED` | Activa la autenticación con Access Manager. El modo multi-tenant la exige. | `false` | No |
| `PLUGIN_AUTH_ADDRESS` | Dirección de Access Manager. | — | Con autenticación |
| `SCHEMA_CACHE_TTL_SECONDS` | TTL del esquema de datasource en caché. Un valor vacío o inválido cae a 5 minutos. | `300` | No |
| `REDIS_HOST` | Host de Valkey o Redis. Respalda la caché de esquemas y el limitador de tasa de la prueba de conexión. | — | No |
| `REDIS_PORT` | Puerto de Redis. | — | No |
| `REDIS_PASSWORD` | Contraseña de Redis. | — | No |
| `REDIS_DB` | Índice de base de datos de Redis. | `0` | No |
| `REDIS_TLS` | Activa TLS hacia Redis. | `false` | No |
| `REDIS_CA_CERT` | CA en PEM codificada en base64, usada cuando `REDIS_TLS=true`. | — | No |
| `MAX_PAGINATION_LIMIT` | Techo del parámetro de consulta `limit` en cada operación de listado. | `100` | No |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Techo de la ventana de fecha de creación en cada operación de listado, en meses. | `1` | No |
**El router se niega a construirse ante dos incompatibilidades de seguridad.** Reporta `tenant middleware requires effective authentication` cuando el modo multi-tenant corre con la autenticación desactivada. Reporta `auth middleware is enabled but its address is empty` cuando `PLUGIN_AUTH_ENABLED=true` y `PLUGIN_AUTH_ADDRESS` está vacío. En ambos casos el Manager no arranca.
## Solo el Worker
***
### Runtime y eventos
| Variable | Descripción | Por defecto | Obligatoria |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `HEALTH_PORT` | Puerto del microservidor de salud del Worker. Sirve `/health`, `/readyz`, `/readyz/tenant/:id` y `/metrics`. El Worker no tiene otro servidor HTTP. | `4007` | No |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Cuántos jobs procesa el Worker en paralelo. | `5` | No |
| `MONGO_MAX_POOL_SIZE` | Tamaño del pool del cliente Mongo para el almacén de metadatos. El ejemplo que se distribuye define `1000`. | `100` | No |
| `STREAMING_ENABLED` | Debe ser `true`. Los eventos terminales de job son un contrato del producto, así que el Worker se niega a arrancar sin streaming. | `false` | Sí |
| `STREAMING_BROKERS` | Lista de brokers bootstrap de la capa de streaming, como pares `host:puerto` separados por comas. El ejemplo que se distribuye define `localhost:9092`. | — | Sí |
| `STREAMING_CLOUDEVENTS_SOURCE` | Source de CloudEvents que se estampa en los eventos que emite el Worker. El ejemplo que se distribuye define `//lerian.fetcher/worker`. | — | Sí |
| `STREAMING_CLIENT_ID` | Identificador del cliente de streaming. | — | No |
| `STREAMING_COMPRESSION` | Códec de compresión: `snappy`, `lz4`, `zstd`, `gzip` o `none`. | `lz4` | No |
| `STREAMING_REQUIRED_ACKS` | Nivel de acuse del productor: `all`, `leader` o `none`. | `all` | No |
| `RABBITMQ_JOB_EVENTS_EXCHANGE` | Exchange que lleva `job.completed` y `job.failed`. El ejemplo que se distribuye usa `fetcher.job.events`. | — | Sí |
| `MULTI_TENANT_RECONCILE_INTERVAL_SEC` | Intervalo con el que el Worker reconcilia los consumidores por tenant contra los tenants activos. | `60` | No |
| `ENGINE_MAX_RESULT_BYTES` | Reemplaza el techo del resultado serializado del engine, como cantidad de bytes. Cero o negativo mantiene el valor por defecto. | `268435456` | No |
| `CRYPTO_ENCRYPT_SECRET_KEY_PLUGIN_CRM` | Clave de cifrado para el camino de extracción de compatibilidad con CRM. | — | No |
| `CRYPTO_HASH_SECRET_KEY_PLUGIN_CRM` | Clave de hash para el camino de extracción de compatibilidad con CRM. | — | No |
**El Worker falla cerrado ante la configuración de eventos.** `STREAMING_ENABLED` sin definir o en `false` aborta el arranque con `STREAMING_ENABLED=true is required for mandatory job event notifications`. Un `RABBITMQ_JOB_EVENTS_EXCHANGE` vacío, un `STREAMING_BROKERS` vacío y un `STREAMING_CLOUDEVENTS_SOURCE` vacío abortan el arranque de la misma forma, igual que un `STREAMING_COMPRESSION` o un `STREAMING_REQUIRED_ACKS` fuera del conjunto aceptado. El Worker nunca cae a un emisor silencioso que no hace nada.
### Almacenamiento de objetos
El Worker escribe cada resultado almacenado en almacenamiento de objetos compatible con S3. El esquema del endpoint controla TLS, así que `http://` lo desactiva.
| Variable | Descripción | Por defecto | Obligatoria |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `OBJECT_STORAGE_ENDPOINT` | Endpoint compatible con S3, por ejemplo `http://minio:9000`. Déjalo sin definir para apuntar a AWS S3. | — | No |
| `OBJECT_STORAGE_REGION` | Región de S3. | `us-east-1` | No |
| `OBJECT_STORAGE_BUCKET` | Bucket para los resultados almacenados. El Worker no arranca sin él. | — | Sí |
| `OBJECT_STORAGE_KEY_PREFIX` | Prefijo de clave aplicado a los objetos almacenados. | — | No |
| `OBJECT_STORAGE_ACCESS_KEY_ID` | Access key ID estática. Defínela junto con `OBJECT_STORAGE_SECRET_KEY`, o deja ambas sin definir para usar la cadena de credenciales de AWS del entorno. | — | No |
| `OBJECT_STORAGE_SECRET_KEY` | Secret access key estática. Defínela junto con `OBJECT_STORAGE_ACCESS_KEY_ID`. Definir solo una de las dos aborta el arranque. | — | No |
| `OBJECT_STORAGE_USE_PATH_STYLE` | Direccionamiento path-style. Ponlo en `true` para MinIO y SeaweedFS. | `false` | No |
Define la expiración de los resultados con una política de ciclo de vida en el bucket. Consulta [Despliegue](/es/fetcher/fetcher-deployment).
### Compatibilidad de firma de mensajes
| Variable | Descripción | Por defecto | Obligatoria |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `RABBITMQ_ALLOW_LEGACY_BODY_SIGNATURE_FALLBACK` | Flag de compatibilidad para una actualización progresiva. También acepta firmas solo sobre el cuerpo en los mensajes consumidos. Una firma solo sobre el cuerpo no vincula el mensaje con su tenant, su job, su exchange ni su routing key. Se distribuye desactivado. Actívalo solo mientras avanzas una flota, y después desactívalo. | `false` | No |
## Datasources internos
***
Los datasources internos son las bases de datos de otros productos Lerian. Fetcher los resuelve sin una conexión registrada por API. Declaras cada uno con un grupo `DATASOURCE_{NAME}_*`, donde `{NAME}` es un prefijo que eliges tú.
Los valores aceptados en `_CONFIG_NAME` son un registro fijo: `midaz_onboarding`, `midaz_transaction` y `plugin_crm`. Fetcher omite cualquier otro nombre y registra una advertencia que nombra tanto el valor rechazado como el conjunto aceptado. Para tus propias bases de datos, registra una conexión a través de la API.
| Variable | Descripción | Ejemplo |
| ------------------------------- | ------------------------------------------------------------------------- | ------------------------- |
| `DATASOURCE_{NAME}_CONFIG_NAME` | Nombre del datasource en el registro. Obligatorio. | `midaz_onboarding` |
| `DATASOURCE_{NAME}_TYPE` | Tipo de datasource, sin distinguir mayúsculas de minúsculas. Obligatorio. | `POSTGRESQL` |
| `DATASOURCE_{NAME}_HOST` | Host. Obligatorio. | `db.internal.example.com` |
| `DATASOURCE_{NAME}_PORT` | Puerto. Obligatorio. | `5432` |
| `DATASOURCE_{NAME}_DATABASE` | Nombre de la base de datos. Obligatorio. | `onboarding` |
| `DATASOURCE_{NAME}_USER` | Usuario. | `fetcher_ro` |
| `DATASOURCE_{NAME}_PASSWORD` | Contraseña. Provéela desde tu gestor de secretos. | — |
| `DATASOURCE_{NAME}_SSLMODE` | Modo TLS. Este es el control de TLS en este camino. | `require` |
| `DATASOURCE_{NAME}_OPTIONS` | Opciones de query-string. Solo MongoDB. | `authSource=admin` |
**Un valor incorrecto omite el datasource, y lo dice.** Un `_TYPE` inválido, un `_SSLMODE` inválido, o un `_HOST` o `_DATABASE` ausente hacen que Fetcher omita ese datasource y registre una advertencia que nombra el config name y el valor ofensor. Fetcher nunca degrada una configuración TLS para alcanzar una base de datos.
## Próximos pasos
***
Dependencias, colas, almacenamiento, escalado y verificaciones de arranque.
Clave maestra, claves derivadas, firma y validación de host.
Sondas, comportamiento de drenaje, métricas y trazas.
Una primera extracción, con o sin infraestructura.