Variables de entorno

Esta referencia lista las variables de entorno que configuran Flowker. La columna Predeterminado lista solo los valores que Flowker aplica en el código cuando no defines una variable. Un guion significa que Flowker no aplica ningún valor de reserva: define la variable explícitamente, con el valor recomendado en la descripción. La columna Obligatorio marca las variables que impiden que el servidor arranque cuando no las defines. Flowker incluye dos binarios. El binario de la API sirve la API HTTP. El binario worker corre el scheduler que dispara los workflows con disparador schedule y sirve solo /health y /readyz. Las variables que aplican a un solo binario lo indican.

Servidor

Variable	Descripción	Predeterminado	Obligatorio
`ENV_NAME`	Etiqueta del entorno de despliegue. `production` o `prod` habilita las protecciones de producción: la autenticación de solicitudes, la autenticación de esquemas XSD y la autenticación de esquemas OpenAPI deben estar habilitadas o el servidor no arranca. Flowker acepta otros valores. Cuando `FLOWKER_SECRETS_BACKEND=tenant-manager`, este valor debe ser no vacío porque forma parte de la ruta del secreto. Recomendado: `production` en producción y `development` en los demás casos.	—	No
`SERVER_ADDRESS`	Dirección de escucha del binario de la API. Cuando está vacía, Fiber se enlaza a todas las interfaces en un puerto efímero asignado por el sistema operativo; defínela explícitamente (recomendado: `:4021`) para tener 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 puedan correr en el mismo host.	`:4022`	No
`VERSION`	Cadena de versión que reporta `/readyz`.	`dev`	No
`CORS_ALLOWED_ORIGINS`	Lista separada por comas de los orígenes CORS permitidos. Vacío significa que no se permite ningún acceso entre orígenes (predeterminado restrictivo).	—	No
`TRUSTED_PROXIES`	Rangos CIDR separados por comas de los proxies confiables (las subredes de tu load balancer/ingress). Cuando se define, `X-Forwarded-For` solo se considera confiable desde estos saltos, por lo que Flowker resuelve la IP real del cliente — incluida la IP que se reenvía a Access Manager para las verificaciones de lista de IP permitidas. Las entradas deben estar en notación CIDR; una IP simple hace fallar el arranque. Vacío deja la funcionalidad desactivada.	—	No

Despliegue

Variable	Descripción	Predeterminado	Obligatorio
`DEPLOYMENT_MODE`	Variante 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 con TLS en el arranque. Los proveedores de fixtures se exponen cuando `DEPLOYMENT_MODE` resuelve a `local` tras recortar los espacios y comparar sin distinguir mayúsculas y minúsculas, siempre que el entorno no sea 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	Predeterminado	Obligatorio
`PLUGIN_AUTH_ENABLED`	Habilita la autenticación del plugin de Access Manager. Cuando es `false`, las rutas de workflow, de webhook y de 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 agregando `/v1/login/oauth/access_token`.	—	Sí (si `PLUGIN_AUTH_ENABLED=true`)
`XSD_SCHEMAS_AUTH_ENABLED`	Requiere autenticación en las rutas `/v1/xsd-schemas`. Un valor sin definir o no reconocido resuelve a `true`. Con un `ENV_NAME` de producción, `false` impide que el servidor arranque.	`true`	No
`OPENAPI_SCHEMAS_AUTH_ENABLED`	Requiere autenticación en las rutas `/v1/openapi-schemas`. Un valor sin definir o no reconocido resuelve a `true`. Con un `ENV_NAME` de producción, `false` impide que el servidor arranque.	`true`	No

Base de datos (MongoDB)

Variable	Descripción	Predeterminado	Obligatorio
`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 vienen del 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 PEM codificado en Base64 para conexiones TLS (por ejemplo, AWS DocumentDB)	—	No

Scheduler

El scheduler dispara los workflows con disparador schedule. Corre en el binario worker y se conecta con sus propios ajustes de Redis, separados de los ajustes de Redis multi-tenant. Nada obliga a esa separación en el arranque: apunta el scheduler a su propia instancia de Redis, o al menos a un índice de base de datos lógica que los eventos de ciclo de vida de tenant no usen.

Variable	Descripción	Predeterminado	Obligatorio
`SCHEDULER_ENABLED`	Interruptor de apagado del scheduler. Un valor sin definir o no reconocido resuelve a `true`; cualquier valor booleano válido que resuelva a `false` (por ejemplo, `false`, `0` o `f`) lo deshabilita. El binario worker se niega a arrancar mientras sea `false`.	`true`	No
`SCHEDULER_REDIS_HOST`	Host del Redis dedicado del scheduler. La cola del scheduler vive aquí, así que defínelo donde 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. Obligatoria solo cuando un worker arranca un scheduler habilitado con `DEPLOYMENT_MODE=saas`; el arranque solo de la API no valida este ajuste.	—	Sí (worker; si `SCHEDULER_ENABLED=true` y `DEPLOYMENT_MODE=saas`)
`SCHEDULER_REDIS_TLS`	Habilita TLS para la conexión Redis del scheduler. Define `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. Cuando el scheduler comparte una instancia de Redis con los eventos de ciclo de vida de tenant, define aquí un índice distinto; ambos usan `0` de forma predeterminada.	`0`	No
`SCHEDULER_CONCURRENCY`	Límite de concurrencia de workers para el servidor de consumo del scheduler. Un valor no positivo resuelve a `10`.	`10`	No

URLs de los servicios de Lerian

Los proveedores internos resuelven su URL base desde el entorno, con la convención {PROVIDER}_BASE_URL, en lugar de hacerlo desde la configuración de proveedor almacenada. Deja una variable vacía para recurrir al valor del documento de configuración almacenado.

Variable	Descripción	Predeterminado	Obligatorio
`MIDAZ_BASE_URL`	URL base del proveedor `ledger`. Alimenta la URL base de transaction y la de onboarding.	—	No
`TRACER_BASE_URL`	URL base del proveedor `tracer`	—	No
`CRM_BASE_URL`	URL base del proveedor `crm`	—	No
`FEES_BASE_URL`	URL base del proveedor `fees`	—	No
`IDENTITY_BASE_URL`	URL base del proveedor `identity`	—	No
`AUTH_BASE_URL`	URL base del proveedor `auth`	—	No
`OPENAPI_NATIVE_PROVIDERS`	Lista de permitidos, separada por comas, de ids de proveedores nativos elegibles para la síntesis a partir de su especificación OpenAPI publicada. Vacío hace elegible a cada proveedor nativo; una lista no vacía limita la elegibilidad a los ids nombrados.	—	No

Registro de esquemas y validación XSD

Variable	Descripción	Predeterminado	Obligatorio
`SCHEMA_REGISTRY_S3_BUCKET`	El almacenamiento en S3 es opcional para el arranque. Si el bucket está vacío, Flowker arranca con una ruta de metadatos en MongoDB, pero las operaciones sobre el contenido de los esquemas XSD y OpenAPI fallan en el momento de uso; configura un bucket para tener un registro de esquemas funcional.	—	No
`SCHEMA_REGISTRY_S3_REGION`	Fija la región de AWS del bucket del registro de esquemas. Vacío resuelve la región a través de la cadena estándar del SDK de AWS (`AWS_REGION` o configuración compartida).	—	No
`SCHEMA_REGISTRY_CACHE_TTL_SEC`	TTL del cache de especificaciones analizadas detrás del resolutor nativo de esquemas de salida (segundos). Un cambio en una especificación publicada se toma en la siguiente descarga cuyo ETag difiera, sin importar el TTL.	`300`	No
`XSD_VALIDATOR_URL`	URL base del sidecar validador de XSD (por ejemplo `http://xsd-validator:8081`). Déjala vacía para correr sin validación de esquemas XML.	—	No
`XSD_VALIDATOR_ALLOW_INSECURE_HTTP`	Un `true` recortado y sin distinción de mayúsculas habilita `http://` en texto plano para `XSD_VALIDATOR_URL`; `1`, `t` y `yes` no.	`false`	No

Secretos

Variable	Descripción	Predeterminado	Obligatorio
`FLOWKER_SECRETS_BACKEND`	Backend que resuelve las credenciales de integraciones externas. `tenant-manager` selecciona el lector de AWS Secrets Manager; sin definir, deshabilita la resolución de secretos. Cualquier otro valor impide que el servidor arranque.	—	No
`FLOWKER_SECRETS_CACHE_TTL_SEC`	TTL del cache de secretos en memoria (segundos)	`30`	No
`FLOWKER_SECRETS_APPLICATION_NAME`	Segmento de ruta `applicationName` que se usa al leer credenciales del almacén del 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 tokens del Tenant Manager

Flowker emite un token Bearer con ámbito de plataforma para llamar a los endpoints de escritura del Tenant Manager. La emisión de tokens requiere WORKOS_TM_TOKEN_URL, WORKOS_TM_CLIENT_ID y WORKOS_TM_CLIENT_SECRET juntas. WORKOS_TM_SCOPE es opcional, pero un valor no vacío requiere esas tres variables de credenciales. WORKOS_TM_SERVICE_NAME solo sobrescribe el nombre del servicio. Deja sin definir la URL del token, el client id, el client secret y el ámbito para deshabilitar la emisión. Una configuración parcial impide que el servidor arranque. La URL base del Tenant Manager viene de MULTI_TENANT_URL.

Variable	Descripción	Predeterminado	Obligatorio
`WORKOS_TM_TOKEN_URL`	Endpoint de token OAuth 2.0 que emite el Bearer con ámbito de plataforma	—	Sí (las tres, o ninguna)
`WORKOS_TM_CLIENT_ID`	Client id para la concesión `client_credentials`	—	Sí (las tres, o ninguna)
`WORKOS_TM_CLIENT_SECRET`	Client secret para la concesión `client_credentials`. Inyéctalo a través de tu gestor de secretos; nunca se escribe en los logs.	—	Sí (las tres, o ninguna)
`WORKOS_TM_SCOPE`	Ámbito delimitado por espacios que se solicita con la concesión. Definirlo solo, sin las tres credenciales, impide que el servidor arranque.	—	No
`WORKOS_TM_SERVICE_NAME`	El nombre de servicio de Flowker tal como lo conoce el Tenant Manager. Debe coincidir con `FLOWKER_SECRETS_APPLICATION_NAME`.	`flowker`	No

Multi-tenant

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

Variable	Descripción	Predeterminado	Obligatorio
`MULTI_TENANT_ENABLED`	Habilita la resolución de conexiones por tenant	`false`	No
`MULTI_TENANT_URL`	URL de la API del Tenant Manager	—	Sí (si `MULTI_TENANT_ENABLED=true`)
`MULTI_TENANT_SERVICE_API_KEY`	API key para el endpoint de ajustes del Tenant Manager	—	Sí (si `MULTI_TENANT_ENABLED=true`)
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	Permite una URL `http://` en texto plano del Tenant Manager. Nunca lo habilites en producción — las credenciales viajan en texto plano.	`false`	No
`MULTI_TENANT_REDIS_HOST`	Host de Redis para los eventos de ciclo de vida de tenant. En despliegues multi-tenant, configura un endpoint alcanzable para que la invalidación de cache, la rotación de credenciales y las actualizaciones de conexión lleguen a Flowker. Omítelo solo cuando aceptes que no haya entrega de eventos de ciclo de vida y un cache por réplica para los validadores compilados de solicitudes OpenAPI.	—	No
`MULTI_TENANT_REDIS_PORT`	Puerto de Redis	`6379`	No
`MULTI_TENANT_REDIS_PASSWORD`	Contraseña de Redis	—	No
`MULTI_TENANT_REDIS_TLS`	Habilita TLS para la conexión Redis	`false`	No
`MULTI_TENANT_MAX_TENANT_POOLS`	Límite flexible de los pools de conexión por tenant en cache. Sin definir, deja el número de pools sin límite. Recomendado: `100`.	—	No
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	Cuánto tiempo debe permanecer inactivo un pool de tenant antes de volverse elegible para expulsión (segundos). Recomendado: `300`.	—	No
`MULTI_TENANT_TIMEOUT`	Timeout de las solicitudes al Tenant Manager (segundos). Sin definir, deja el cliente HTTP sin timeout. Recomendado: `30`.	—	No
`MULTI_TENANT_CACHE_TTL_SEC`	TTL del cache de ajustes de tenant (segundos). Un valor positivo aplica al cache local de tenants y al cache del cliente del Tenant Manager. Cuando no se define o no es positivo, sus valores predeterminados son `43200` segundos (12 horas) y `3600` segundos (1 hora), respectivamente. Recomendado: `120`.	`43200` local / `3600` cliente del Tenant Manager	No
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	Fallos consecutivos que abren el circuito. Un valor gobierna tanto el breaker por configuración de proveedor como el breaker del cliente HTTP del Tenant Manager. Sin definir, deja el breaker por configuración de proveedor en 20 y el breaker del Tenant Manager inactivo, así que defínelo explícitamente en despliegues multi-tenant.	`20` (por configuración de proveedor)	No
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	Timeout de recuperación del circuit breaker (segundos)	`30`	No

Cache de tokens

Límites del cache compartido de tokens OAuth 2.0 que usa la autenticación de proveedores (flujos de endpoint de token OIDC y OAuth2).

Variable	Descripción	Predeterminado	Obligatorio
`TOKEN_CACHE_MAX_TTL_SEC`	Tiempo máximo durante el cual se confía en cualquier token en cache, sin importar el `expires_in` del proveedor	`3600`	No
`TOKEN_CACHE_JANITOR_INTERVAL_SEC`	Con qué frecuencia el janitor en segundo plano expulsa los tokens vencidos (segundos)	`300`	No
`TOKEN_CACHE_REFRESH_BUFFER_SEC`	Cuánto antes del vencimiento se actualiza de forma proactiva un token en cache (segundos)	`60`	No
`TOKEN_CACHE_TENANT_SCOPED_DISABLED`	Desactiva el cache de tokens con ámbito de tenant. El ámbito de tenant es el predeterminado en modo multi-tenant; deshabilitarlo vuelve a compartir un solo cache entre tenants.	`false`	No

Observabilidad

Variable	Descripción	Predeterminado	Obligatorio
`ENABLE_TELEMETRY`	Habilita la instrumentación de OpenTelemetry	`false`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del exportador OTLP	—	Sí (si `ENABLE_TELEMETRY=true`)
`OTEL_RESOURCE_SERVICE_NAME`	Nombre del servicio para la telemetría. Recomendado: `flowker`.	—	No
`OTEL_RESOURCE_SERVICE_VERSION`	Versión del servicio para la telemetría	—	No
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Etiqueta del entorno de despliegue	—	No
`OTEL_LIBRARY_NAME`	Nombre de la librería de instrumentación. El logger la requiere en cada arranque, incluso cuando `ENABLE_TELEMETRY` es `false`. Recomendado: `flowker`.	—	Sí
`SKIP_LIB_COMMONS_TELEMETRY`	Omite la telemetría de la librería commons	`false`	No
`LOG_LEVEL`	Nivel de log (`debug`, `info`, `warn`, `error`, `dpanic`, `panic` o `fatal`; sin distinguir mayúsculas y minúsculas). Sin definir, el nivel sigue a `ENV_NAME`: `development` y `local` escriben logs en `debug`, todos los demás valores escriben logs en `info`. Un nivel no reconocido impide que el servidor arranque.	—	No

Seguridad

Variable	Descripción	Predeterminado	Obligatorio
`SSRF_ALLOW_PRIVATE`	Permite llamadas HTTP de los ejecutores a IPs privadas. Solo la cadena exacta `true` lo habilita. Nunca lo habilites en producción.	`false`	No
`ALLOW_INSECURE_TLS`	Omite el requisito de TLS en los clientes de infraestructura compartidos y en su lugar escribe una advertencia en el log. Acepta `true`, `1`, `yes` u `on`. Déjala sin definir en producción para que el TLS real siga siendo obligatorio.	`false`	No
`HTTP_MAX_BODY_BYTES`	Límite del cuerpo de solicitud que se envía y del cuerpo de respuesta que se lee en las llamadas HTTP salientes a proveedores (bytes). Un valor cero o negativo resuelve al predeterminado.	`10485760` (10 MiB)	No
`FAULT_INJECTION_ENABLED`	Habilita la inyección de fallos para pruebas	`false`	No

Swagger

Variable	Descripción	Predeterminado	Obligatorio
`SWAGGER_ENABLED`	Sirve 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

Resumen

Guías

Console

Operaciones

Variables de entorno

Servidor

Despliegue

Autenticación

Base de datos (MongoDB)

Scheduler

URLs de los servicios de Lerian

Registro de esquemas y validación XSD

Secretos

Emisión de tokens del Tenant Manager

Multi-tenant

Cache de tokens

Observabilidad

Seguridad

Swagger

​Servidor

​Despliegue

​Autenticación

​Base de datos (MongoDB)

​Scheduler

​URLs de los servicios de Lerian

​Registro de esquemas y validación XSD

​Secretos

​Emisión de tokens del Tenant Manager

​Multi-tenant

​Cache de tokens

​Observabilidad

​Seguridad

​Swagger

Servidor

Despliegue

Autenticación

Base de datos (MongoDB)

Scheduler

URLs de los servicios de Lerian

Registro de esquemas y validación XSD

Secretos

Emisión de tokens del Tenant Manager

Multi-tenant

Cache de tokens

Observabilidad

Seguridad

Swagger