Variables de entorno

Consulta la referencia completa de las variables de entorno utilizadas para configurar Flowker, organizadas por categoría para una búsqueda ágil.

Esta referencia lista las variables de entorno que configuran Flowker.

La columna Por defecto solo lista los valores que Flowker aplica en el código cuando una variable no está definida. Un guion significa que Flowker no aplica ningún valor de reserva: define la variable explícitamente, usando el valor recomendado en la descripción. La columna Obligatoria marca las variables cuya ausencia impide que el servidor arranque.

Flowker se distribuye en dos binarios. El binario de API sirve la API HTTP. El binario worker ejecuta el scheduler que dispara los workflows con trigger schedule y solo sirve /health y /readyz. Las variables que aplican a un solo binario lo indican.

​

Servidor

Variable	Descripción	Por defecto	Obligatoria
ENV_NAME	Nombre del entorno. Define uno de production, staging, uat, development o local — cualquier otro valor, incluido uno vacío, impide que el servidor arranque. production activa las protecciones de producción: la autenticación de peticiones, la de esquemas XSD y la de esquemas OpenAPI deben estar habilitadas o el servidor no arranca. Recomendado: production en producción y development en el resto.	—	Sí
SERVER_ADDRESS	Dirección de escucha del binario de API. Si está vacía, Fiber enlaza todas las interfaces en un puerto efímero asignado por el sistema operativo; defínela explícitamente (recomendado: :4021) para una dirección predecible.	—	No
WORKER_SERVER_ADDRESS	Dirección de escucha de la app /health y /readyz del binario worker. Debe ser distinta de SERVER_ADDRESS para que ambos binarios corran en el mismo host.	:4022	No
VERSION	Cadena de versión que reporta /readyz.	dev	No
CORS_ALLOWED_ORIGINS	Lista separada por comas de orígenes CORS permitidos. Vacío significa que no se permite acceso cross-origin (valor por defecto restrictivo).	—	No
TRUSTED_PROXIES	Rangos CIDR separados por comas de los proxies confiables (las subredes de tu load balancer/ingress). Cuando está definido, X-Forwarded-For solo se confía desde esos saltos, por lo que Flowker resuelve la IP real del cliente — incluida la IP reenviada al Access Manager para las verificaciones de IP-allowlist. Las entradas deben usar notación CIDR; una IP sin máscara falla al arrancar. Vacío deja la funcionalidad desactivada.	—	No

​

Despliegue

Variable	Descripción	Por defecto	Obligatoria
DEPLOYMENT_MODE	Modalidad de despliegue: local, byoc o saas. En saas, Flowker valida TLS para un MONGO_URI estático no vacío; las conexiones MongoDB multi-tenant se resuelven después y no se validan para TLS durante el arranque. Los providers de fixture se exponen cuando DEPLOYMENT_MODE se resuelve como local tras eliminar espacios y comparar sin distinguir mayúsculas, siempre que el entorno no sea de producción. /readyz reporta local cuando la variable no está definida. Recomendado: byoc o saas fuera de una estación de trabajo de desarrollo.	—	No

​

Autenticación

Variable	Descripción	Por defecto	Obligatoria
PLUGIN_AUTH_ENABLED	Habilitar autenticación mediante el plugin de Access Manager. Cuando es false, las rutas de workflow, webhook y gestión no requieren autenticación (solo para desarrollo local). Con un ENV_NAME de producción, false impide que el servidor arranque.	false	No
PLUGIN_AUTH_ADDRESS	Dirección del servicio Access Manager. El endpoint de token machine-to-machine se deriva de ella añadiendo /v1/login/oauth/access_token.	—	Sí (si PLUGIN_AUTH_ENABLED=true)
XSD_SCHEMAS_AUTH_ENABLED	Exigir autenticación en las rutas /v1/xsd-schemas. Un valor ausente o no reconocido se resuelve como true. Con un ENV_NAME de producción, false impide que el servidor arranque.	true	No
OPENAPI_SCHEMAS_AUTH_ENABLED	Exigir autenticación en las rutas /v1/openapi-schemas. Un valor ausente o no reconocido se resuelve como true. Con un ENV_NAME de producción, false impide que el servidor arranque.	true	No

​

Base de datos (MongoDB)

Variable	Descripción	Por defecto	Obligatoria
MONGO_URI	URI de conexión de MongoDB. En modo multi-tenant no se abre ningún pool estático y las conexiones por tenant provienen de Tenant Manager.	—	Sí (modo single-tenant)
MONGO_DB_NAME	Nombre de la base de datos MongoDB. Recomendado: flowker.	—	Sí (modo single-tenant)
MONGO_TLS_CA_CERT	Certificado CA en formato PEM codificado en Base64 para conexiones TLS (p. ej., AWS DocumentDB)	—	No

​

Scheduler

El scheduler dispara los workflows con trigger schedule. Corre en el binario worker y usa su propia configuración de Redis, separada de la configuración de Redis multi-tenant. El arranque no fuerza esa separación: apunta el scheduler a su propia instancia de Redis o, como mínimo, a un índice de base de datos lógica distinto del usado para los eventos de ciclo de vida de tenants.

Variable	Descripción	Por defecto	Obligatoria
SCHEDULER_ENABLED	Interruptor general del scheduler. Un valor ausente o no reconocido se resuelve como true; cualquier valor booleano válido que se resuelva como false (por ejemplo, false, 0 o f) lo desactiva. El binario worker no arranca mientras esté en false.	true	No
SCHEDULER_REDIS_HOST	Host del Redis dedicado del scheduler. La cola del scheduler vive ahí, así que defínelo dondequiera que el scheduler esté habilitado: sin host, el binario worker no arranca y ningún workflow programado se dispara.	—	Sí (si SCHEDULER_ENABLED=true)
SCHEDULER_REDIS_PORT	Puerto del Redis del scheduler	6379	No
SCHEDULER_REDIS_PASSWORD	Contraseña del Redis del scheduler. Solo es obligatoria cuando un worker inicia el scheduler habilitado con DEPLOYMENT_MODE=saas; el arranque solo de API no valida esta variable.	—	Sí (worker; si SCHEDULER_ENABLED=true y DEPLOYMENT_MODE=saas)
SCHEDULER_REDIS_TLS	Habilitar TLS para la conexión con el Redis del scheduler. Ponlo en true en producción y apunta el scheduler a un Redis que termine TLS.	false	No
SCHEDULER_REDIS_DB	Índice de base de datos lógica de Redis para la cola. Mantenlo distinto del índice de eventos de tenants.	0	No
SCHEDULER_CONCURRENCY	Límite de concurrencia de workers del servidor de consumo del scheduler. Un valor no positivo se resuelve como 10.	10	No

​

URLs de servicios Lerian

Los providers internos resuelven su URL base desde el entorno, siguiendo la convención {PROVIDER}_BASE_URL, en lugar de tomarla de la configuración de provider almacenada. Deja una variable vacía para usar el valor del documento de configuración almacenado.

Variable	Descripción	Por defecto	Obligatoria
MIDAZ_BASE_URL	URL base del provider ledger. Alimenta tanto la URL base de transacciones como la de onboarding.	—	No
TRACER_BASE_URL	URL base del provider tracer	—	No
CRM_BASE_URL	URL base del provider crm	—	No
FEES_BASE_URL	URL base del provider fees	—	No
IDENTITY_BASE_URL	URL base del provider identity	—	No
AUTH_BASE_URL	URL base del provider auth	—	No
OPENAPI_NATIVE_PROVIDERS	Lista separada por comas de ids de providers nativos elegibles para sintetizarse desde su especificación OpenAPI publicada. Vacío hace elegible a todos los providers nativos; una lista no vacía restringe la elegibilidad a los ids indicados.	—	No

​

Registro de esquemas y validación XSD

Variable	Descripción	Por defecto	Obligatoria
SCHEMA_REGISTRY_S3_BUCKET	El almacenamiento S3 es opcional para el arranque. Si el bucket está vacío, Flowker inicia con una ruta de metadatos en MongoDB, pero las operaciones de contenido de esquemas XSD y OpenAPI fallan al usarse; configura un registro de esquemas funcional.	—	No
SCHEMA_REGISTRY_S3_REGION	Fija la región AWS del bucket del registro de esquemas. Vacío resuelve la región mediante la cadena estándar del SDK de AWS (AWS_REGION o la configuración compartida).	—	No
SCHEMA_REGISTRY_CACHE_TTL_SEC	TTL de la caché de especificaciones parseadas que respalda el resolutor de esquemas de salida nativos (segundos). Un cambio en una especificación publicada se recoge en la siguiente descarga cuyo ETag difiera, sin importar el TTL.	300	No
XSD_VALIDATOR_URL	URL base del sidecar validador XSD (p. ej., http://xsd-validator:8081). Déjala vacía para operar sin validación de esquemas XML.	—	No
XSD_VALIDATOR_ALLOW_INSECURE_HTTP	Un true después de eliminar espacios y sin distinguir mayúsculas habilita http:// sin cifrar para XSD_VALIDATOR_URL; 1, t y yes no.	false	No

​

Secretos

Variable	Descripción	Por defecto	Obligatoria
FLOWKER_SECRETS_BACKEND	Backend que resuelve las credenciales de integraciones externas. tenant-manager selecciona el lector de AWS Secrets Manager; sin definir, la resolución de secretos queda desactivada. Cualquier otro valor impide que el servidor arranque.	—	No
FLOWKER_SECRETS_CACHE_TTL_SEC	TTL de la caché de secretos en memoria (segundos)	30	No
FLOWKER_SECRETS_APPLICATION_NAME	Segmento de ruta applicationName usado al leer credenciales del almacén de Tenant Manager. Debe coincidir con WORKOS_TM_SERVICE_NAME para que la ruta de lectura y la de escritura resuelvan la misma identidad de servicio.	flowker	No

​

Emisión de token de Tenant Manager

Flowker emite un token bearer con alcance de plataforma para llamar a los endpoints de escritura de Tenant Manager. La emisión de tokens exige definir juntas WORKOS_TM_TOKEN_URL, WORKOS_TM_CLIENT_ID y WORKOS_TM_CLIENT_SECRET. WORKOS_TM_SCOPE es opcional, pero un valor no vacío exige esas tres variables de credenciales. WORKOS_TM_SERVICE_NAME solo reemplaza el nombre del servicio. Deja sin definir la URL de token, el client ID, el client secret y el scope para desactivar la emisión. Una configuración parcial impide que el servidor arranque. La URL base de Tenant Manager proviene de MULTI_TENANT_URL.

Variable	Descripción	Por defecto	Obligatoria
WORKOS_TM_TOKEN_URL	Endpoint de token OAuth 2.0 que emite el bearer con alcance de plataforma	—	Sí (las tres, o ninguna)
WORKOS_TM_CLIENT_ID	Client id para el grant client_credentials	—	Sí (las tres, o ninguna)
WORKOS_TM_CLIENT_SECRET	Client secret para el grant client_credentials. Inyéctalo mediante tu gestor de secretos; nunca se escribe en los logs.	—	Sí (las tres, o ninguna)
WORKOS_TM_SCOPE	Alcance, delimitado por espacios, solicitado con el grant. Definirlo solo, sin las tres credenciales, impide que el servidor arranque.	—	No
WORKOS_TM_SERVICE_NAME	Nombre del servicio Flowker tal como lo conoce Tenant Manager. Debe coincidir con FLOWKER_SECRETS_APPLICATION_NAME.	flowker	No

​

Multi-tenant

Cuando MULTI_TENANT_ENABLED=true, las conexiones a base de datos se resuelven por tenant a través de Tenant Manager. Cuando es false (por defecto), Flowker opera en modo single-tenant con conexiones estáticas.

Variable	Descripción	Por defecto	Obligatoria
MULTI_TENANT_ENABLED	Habilitar la resolución de conexiones por tenant	false	No
MULTI_TENANT_URL	URL de la API de Tenant Manager	—	Sí (si MULTI_TENANT_ENABLED=true)
MULTI_TENANT_SERVICE_API_KEY	API key para el endpoint de settings de Tenant Manager	—	Sí (si MULTI_TENANT_ENABLED=true)
MULTI_TENANT_ALLOW_INSECURE_HTTP	Permitir una URL de Tenant Manager en http:// sin cifrar. Nunca lo habilites en producción — las credenciales viajan en texto plano.	false	No
MULTI_TENANT_REDIS_HOST	Host de Redis para eventos de ciclo de vida de tenants. En despliegues multi-tenant, configura un endpoint accesible para que la invalidación de caché, la rotación de credenciales y las actualizaciones de conexiones lleguen a Flowker. Omítelo solo si aceptas no recibir eventos de ciclo de vida y usar una caché por réplica para validadores de solicitudes OpenAPI compilados.	—	No
MULTI_TENANT_REDIS_PORT	Puerto de Redis	6379	No
MULTI_TENANT_REDIS_PASSWORD	Contraseña de Redis	—	No
MULTI_TENANT_REDIS_TLS	Habilitar TLS para la conexión con Redis	false	No
MULTI_TENANT_MAX_TENANT_POOLS	Límite flexible de pools de conexión por tenant en caché. Sin definir, el número de pools queda sin límite. Recomendado: 100.	—	No
MULTI_TENANT_IDLE_TIMEOUT_SEC	Cuánto tiempo debe permanecer inactivo un pool de tenant antes de ser elegible para desalojo (segundos). Recomendado: 300.	—	No
MULTI_TENANT_TIMEOUT	Timeout de solicitud a Tenant Manager (segundos). Sin definir, el cliente HTTP queda sin timeout. Recomendado: 30.	—	No
MULTI_TENANT_CACHE_TTL_SEC	TTL de la caché de configuración de tenants (segundos). Un valor positivo se aplica a la caché local de tenants y a la caché del cliente de Tenant Manager. Sin definir o con un valor no positivo, sus valores por defecto son 43200 segundos (12 horas) y 3600 segundos (1 hora), respectivamente. Recomendado: 120.	43200 local / 3600 cliente Tenant Manager	No
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD	Fallos consecutivos que abren el circuito. Un mismo valor gobierna el circuit breaker por configuración de provider y el del cliente HTTP de Tenant Manager. Sin definir, el breaker por configuración de provider queda en 20 y el de Tenant Manager queda inactivo, así que defínelo explícitamente en despliegues multi-tenant.	20 (por configuración de provider)	No
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC	Timeout de recuperación del circuit breaker (segundos)	30	No

​

Caché de tokens

Límites para la caché compartida de tokens OAuth 2.0 utilizada por la autenticación de providers (flujos OIDC y OAuth2 token-endpoint).

Variable	Descripción	Por defecto	Obligatoria
TOKEN_CACHE_MAX_TTL_SEC	Tiempo máximo que se confía en cualquier token en caché, sin importar el expires_in del provider	3600	No
TOKEN_CACHE_JANITOR_INTERVAL_SEC	Frecuencia con la que el proceso de limpieza en segundo plano elimina tokens expirados (segundos)	300	No
TOKEN_CACHE_REFRESH_BUFFER_SEC	Cuánto antes de la expiración se renueva de forma proactiva un token en caché (segundos)	60	No
TOKEN_CACHE_TENANT_SCOPED_DISABLED	Desactivar el alcance por tenant de la caché de tokens. El alcance por tenant es el valor por defecto en modo multi-tenant; desactivarlo vuelve a compartir una sola caché entre tenants.	false	No

​

Observabilidad

Variable	Descripción	Por defecto	Obligatoria
ENABLE_TELEMETRY	Habilitar instrumentación OpenTelemetry	false	No
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint del exportador OTLP	—	Sí (si ENABLE_TELEMETRY=true)
OTEL_RESOURCE_SERVICE_NAME	Nombre del servicio para telemetría. Recomendado: flowker.	—	No
OTEL_RESOURCE_SERVICE_VERSION	Versión del servicio para telemetría	—	No
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Etiqueta de entorno de despliegue	—	No
OTEL_LIBRARY_NAME	Nombre de la biblioteca de instrumentación. El logger la exige en cada arranque, incluso cuando ENABLE_TELEMETRY es false. Recomendado: flowker.	—	Sí
SKIP_LIB_COMMONS_TELEMETRY	Omitir telemetría de la biblioteca commons	false	No
LOG_LEVEL	Nivel de log (debug, info, warn, error, dpanic, panic o fatal; sin distinguir mayúsculas). Sin definir, el nivel sigue a ENV_NAME: development y local registran en debug, y cualquier otro valor registra en info. Un nivel no reconocido impide que el servidor arranque.	—	No

​

Seguridad

Variable	Descripción	Por defecto	Obligatoria
SSRF_ALLOW_PRIVATE	Permitir llamadas HTTP de executors a IPs privadas. Solo la cadena exacta true lo habilita. Nunca lo habilites en producción.	false	No
ALLOW_INSECURE_TLS	Omitir la exigencia de TLS en los clientes de infraestructura compartidos y registrar una advertencia en su lugar. Acepta true, 1, yes u on. Déjala sin definir en producción para que TLS siga siendo obligatorio.	false	No
HTTP_MAX_BODY_BYTES	Límite del cuerpo de la petición enviada y del cuerpo de la respuesta leída en las llamadas HTTP salientes a providers (bytes). Un valor cero o negativo se resuelve al valor por defecto.	10485760 (10 MiB)	No
FAULT_INJECTION_ENABLED	Habilitar inyección de fallos para pruebas	false	No

​

Swagger

Variable	Descripción	Por defecto	Obligatoria
SWAGGER_ENABLED	Servir la especificación OpenAPI generada y la UI de documentación en /openapi/openapi.json, /openapi/openapi.yaml y /openapi/docs	false	No
SWAGGER_TITLE	Título de la página de la UI de documentación	—	No