> ## 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. # Variáveis de ambiente > Referência das variáveis de ambiente do Flowker, cobrindo servidor, agendador, deploy, autenticação, MongoDB, schema registry, segredos e configurações multi-tenant. Esta referência lista as variáveis de ambiente que configuram o Flowker. A coluna **Padrão** lista apenas os valores que o Flowker aplica em código quando você não define uma variável. Um traço significa que o Flowker não aplica nenhum fallback: defina a variável explicitamente, usando o valor recomendado na descrição. A coluna **Obrigatório** marca as variáveis que impedem o servidor de iniciar quando você não as define. O Flowker entrega dois binários. O binário da API serve a API HTTP. O binário do worker roda o agendador que dispara os workflows acionados por `schedule` e serve apenas `/health` e `/readyz`. As variáveis que valem para um binário dizem isso. ## Servidor | Variável | Descrição | Padrão | Obrigatório | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- | | `ENV_NAME` | Rótulo do ambiente de deploy. `production` ou `prod` liga as proteções de produção: a autenticação de requisição, a autenticação de schema XSD e a autenticação de schema OpenAPI devem estar habilitadas ou o servidor não inicia. O Flowker aceita outros valores. Quando `FLOWKER_SECRETS_BACKEND=tenant-manager`, este valor deve ser não vazio porque ele faz parte do caminho do segredo. Recomendado: `production` em produção e `development` nos demais ambientes. | — | Não | | `SERVER_ADDRESS` | Endereço de escuta do binário da API. Quando vazio, o Fiber escuta em todas as interfaces em uma porta efêmera atribuída pelo sistema operacional; defina-o explicitamente (recomendado: `:4021`) para ter um endereço previsível. | — | Não | | `WORKER_SERVER_ADDRESS` | Endereço de escuta do app de `/health` e `/readyz` do binário do worker. Deve ser diferente de `SERVER_ADDRESS` para os dois binários rodarem no mesmo host. | `:4022` | Não | | `VERSION` | String de versão informada por `/readyz`. | `dev` | Não | | `CORS_ALLOWED_ORIGINS` | Lista de origens CORS permitidas, separada por vírgulas. Vazia significa que nenhum acesso cross-origin é permitido (padrão restritivo). | — | Não | | `TRUSTED_PROXIES` | Faixas CIDR dos proxies confiáveis, separadas por vírgulas (as sub-redes do seu load balancer ou ingress). Quando definida, `X-Forwarded-For` é confiável apenas a partir desses saltos, então o Flowker resolve o IP real do cliente — incluindo o IP encaminhado ao Access Manager para as verificações de lista de IPs permitidos. As entradas devem estar em notação CIDR; um IP puro faz a inicialização falhar. Vazia deixa o recurso desligado. | — | Não | ## Deploy | Variável | Descrição | Padrão | Obrigatório | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | | `DEPLOYMENT_MODE` | Variante do deploy: `local`, `byoc` ou `saas`. Em `saas`, o Flowker valida TLS para um `MONGO_URI` estático não vazio; as conexões MongoDB multi-tenant são resolvidas depois e não passam por validação de TLS no bootstrap. Os provedores de fixture ficam expostos quando `DEPLOYMENT_MODE` resolve para `local` depois de remover os espaços e comparar sem diferenciar maiúsculas, desde que o ambiente não seja de produção. O `/readyz` informa `local` quando a variável não está definida. Recomendado: `byoc` ou `saas` fora de uma estação de trabalho de desenvolvimento. | — | Não | ## Autenticação | Variável | Descrição | Padrão | Obrigatório | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----------------------------------- | | `PLUGIN_AUTH_ENABLED` | Habilita a autenticação pelo plugin do Access Manager. Quando `false`, as rotas de workflow, de webhook e de gestão não exigem autenticação (apenas desenvolvimento local). Com um `ENV_NAME` de produção, `false` impede o servidor de iniciar. | `false` | Não | | `PLUGIN_AUTH_ADDRESS` | Endereço do serviço Access Manager. O endpoint de token máquina a máquina deriva dele com o acréscimo de `/v1/login/oauth/access_token`. | — | Sim (se `PLUGIN_AUTH_ENABLED=true`) | | `XSD_SCHEMAS_AUTH_ENABLED` | Exige autenticação nas rotas `/v1/xsd-schemas`. Um valor não definido ou não reconhecido resolve para `true`. Com um `ENV_NAME` de produção, `false` impede o servidor de iniciar. | `true` | Não | | `OPENAPI_SCHEMAS_AUTH_ENABLED` | Exige autenticação nas rotas `/v1/openapi-schemas`. Um valor não definido ou não reconhecido resolve para `true`. Com um `ENV_NAME` de produção, `false` impede o servidor de iniciar. | `true` | Não | ## Banco de dados (MongoDB) | Variável | Descrição | Padrão | Obrigatório | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------ | | `MONGO_URI` | URI de conexão do MongoDB. No modo multi-tenant nenhum pool estático é aberto e as conexões por tenant vêm do Tenant Manager. | — | Sim (modo single-tenant) | | `MONGO_DB_NAME` | Nome do banco de dados MongoDB. Recomendado: `flowker`. | — | Sim (modo single-tenant) | | `MONGO_TLS_CA_CERT` | Certificado CA em PEM codificado em Base64 para conexões TLS (por exemplo, AWS DocumentDB) | — | Não |

Agendador

O agendador dispara os workflows acionados por `schedule`. Ele roda no binário do worker e conecta pelas configurações de Redis próprias dele, separadas das configurações de Redis multi-tenant. Nada garante essa separação na inicialização: aponte o agendador para uma instância de Redis própria, ou pelo menos para um índice de banco lógico que os eventos de ciclo de vida de tenant não usem. | Variável | Descrição | Padrão | Obrigatório | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ | | `SCHEDULER_ENABLED` | Chave de desligamento do agendador. Um valor não definido ou não reconhecido resolve para `true`; qualquer valor booleano válido que resolva para `false` (por exemplo, `false`, `0` ou `f`) o desabilita. O binário do worker se recusa a iniciar enquanto ela estiver em `false`. | `true` | Não | | `SCHEDULER_REDIS_HOST` | Host do Redis dedicado ao agendador. A fila do agendador fica aqui, então defina-o sempre que o agendador estiver habilitado: sem host, o binário do worker não inicia e nenhum workflow agendado dispara. | — | Sim (se `SCHEDULER_ENABLED=true`) | | `SCHEDULER_REDIS_PORT` | Porta do Redis do agendador | `6379` | Não | | `SCHEDULER_REDIS_PASSWORD` | Senha do Redis do agendador. Obrigatória apenas quando um worker inicia um agendador habilitado com `DEPLOYMENT_MODE=saas`; a inicialização apenas da API não valida esta configuração. | — | Sim (worker; se `SCHEDULER_ENABLED=true` e `DEPLOYMENT_MODE=saas`) | | `SCHEDULER_REDIS_TLS` | Habilita TLS na conexão com o Redis do agendador. Defina `true` em produção e aponte o agendador para um Redis que termina TLS. | `false` | Não | | `SCHEDULER_REDIS_DB` | Índice do banco lógico do Redis para a fila. Quando o agendador divide a instância de Redis com os eventos de ciclo de vida de tenant, defina um índice distinto aqui; os dois têm `0` como padrão. | `0` | Não | | `SCHEDULER_CONCURRENCY` | Limite de concorrência de workers do servidor de consumo do agendador. Um valor não positivo resolve para `10`. | `10` | Não | ## URLs dos serviços Lerian Os provedores internos resolvem a URL base deles pelo ambiente, seguindo a convenção `{PROVIDER}_BASE_URL`, em vez da configuração de provedor guardada. Deixe uma variável vazia para usar o valor do documento de configuração guardado. | Variável | Descrição | Padrão | Obrigatório | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | | `MIDAZ_BASE_URL` | URL base do provedor `ledger`. Alimenta tanto a URL base de transaction quanto a de onboarding. | — | Não | | `TRACER_BASE_URL` | URL base do provedor `tracer` | — | Não | | `CRM_BASE_URL` | URL base do provedor `crm` | — | Não | | `FEES_BASE_URL` | URL base do provedor `fees` | — | Não | | `IDENTITY_BASE_URL` | URL base do provedor `identity` | — | Não | | `AUTH_BASE_URL` | URL base do provedor `auth` | — | Não | | `OPENAPI_NATIVE_PROVIDERS` | Lista de permissão, separada por vírgulas, de ids de provedores nativos elegíveis à síntese a partir da spec OpenAPI publicada deles. Vazia deixa todos os provedores nativos elegíveis; uma lista não vazia restringe a elegibilidade aos ids indicados. | — | Não | ## Schema registry e validação XSD | Variável | Descrição | Padrão | Obrigatório | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- | | `SCHEMA_REGISTRY_S3_BUCKET` | O armazenamento em S3 é opcional para o boot. Se o bucket estiver vazio, o Flowker inicia com um caminho de metadados no MongoDB, mas as operações de conteúdo de schema XSD e OpenAPI falham no momento do uso; configure um bucket para ter um schema registry funcional. | — | Não | | `SCHEMA_REGISTRY_S3_REGION` | Fixa a região AWS do bucket do schema registry. Vazia resolve a região pela cadeia padrão do SDK da AWS (`AWS_REGION` ou configuração compartilhada). | — | Não | | `SCHEMA_REGISTRY_CACHE_TTL_SEC` | TTL do cache de specs já processadas por trás do resolvedor de schema de saída nativo (segundos). Uma mudança na spec publicada é adotada na próxima busca cujo ETag seja diferente, independentemente do TTL. | `300` | Não | | `XSD_VALIDATOR_URL` | URL base do sidecar validador de XSD (por exemplo, `http://xsd-validator:8081`). Deixe-a vazia para rodar sem validação de schema XML. | — | Não | | `XSD_VALIDATOR_ALLOW_INSECURE_HTTP` | Um `true` sem espaços e sem diferenciar maiúsculas habilita `http://` em texto claro para `XSD_VALIDATOR_URL`; `1`, `t` e `yes` não habilitam. | `false` | Não | ## Segredos | Variável | Descrição | Padrão | Obrigatório | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- | | `FLOWKER_SECRETS_BACKEND` | Backend que resolve as credenciais de integrações externas. `tenant-manager` escolhe o leitor do AWS Secrets Manager; sem definir, desabilita a resolução de segredos. Qualquer outro valor impede o servidor de iniciar. | — | Não | | `FLOWKER_SECRETS_CACHE_TTL_SEC` | TTL do cache de segredos em memória (segundos) | `30` | Não | | `FLOWKER_SECRETS_APPLICATION_NAME` | Segmento de caminho `applicationName` usado na leitura de credenciais no repositório do Tenant Manager. Ele deve ser igual a `WORKOS_TM_SERVICE_NAME` para o caminho de leitura e o de escrita resolverem a mesma identidade de serviço. | `flowker` | Não | ## Emissão de token do Tenant Manager O Flowker emite um bearer token com escopo de plataforma para chamar os endpoints de escrita do Tenant Manager. A emissão do token exige `WORKOS_TM_TOKEN_URL`, `WORKOS_TM_CLIENT_ID` e `WORKOS_TM_CLIENT_SECRET` juntas. `WORKOS_TM_SCOPE` é opcional, mas um valor não em branco exige essas três variáveis de credencial. `WORKOS_TM_SERVICE_NAME` apenas sobrescreve o nome do serviço. Deixe a URL de token, o client id, o client secret e o escopo sem definir para desabilitar a emissão. Uma configuração parcial impede o servidor de iniciar. A URL base do Tenant Manager vem de `MULTI_TENANT_URL`. | Variável | Descrição | Padrão | Obrigatório | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- | | `WORKOS_TM_TOKEN_URL` | Endpoint de token OAuth 2.0 que emite o bearer com escopo de plataforma | — | Sim (as três, ou nenhuma) | | `WORKOS_TM_CLIENT_ID` | Client id do grant `client_credentials` | — | Sim (as três, ou nenhuma) | | `WORKOS_TM_CLIENT_SECRET` | Client secret do grant `client_credentials`. Injete-o pelo seu gerenciador de segredos; ele nunca vai para o log. | — | Sim (as três, ou nenhuma) | | `WORKOS_TM_SCOPE` | Escopo separado por espaços pedido junto com o grant. Defini-lo sozinho, sem as três credenciais, impede o servidor de iniciar. | — | Não | | `WORKOS_TM_SERVICE_NAME` | O nome de serviço do Flowker como o Tenant Manager o conhece. Ele deve ser igual a `FLOWKER_SECRETS_APPLICATION_NAME`. | `flowker` | Não | ## Multi-tenant Quando `MULTI_TENANT_ENABLED=true`, o Flowker resolve as conexões de banco de dados por tenant pelo Tenant Manager. Quando `false` (padrão), o Flowker roda em modo single-tenant com conexões estáticas. | Variável | Descrição | Padrão | Obrigatório | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------ | | `MULTI_TENANT_ENABLED` | Habilita a resolução de conexão por tenant | `false` | Não | | `MULTI_TENANT_URL` | URL da API do Tenant Manager | — | Sim (se `MULTI_TENANT_ENABLED=true`) | | `MULTI_TENANT_SERVICE_API_KEY` | Chave de API do endpoint de configurações do Tenant Manager | — | Sim (se `MULTI_TENANT_ENABLED=true`) | | `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite uma URL `http://` em texto claro para o Tenant Manager. Nunca habilite em produção — as credenciais trafegam em texto puro. | `false` | Não | | `MULTI_TENANT_REDIS_HOST` | Host do Redis para os eventos de ciclo de vida de tenant. Em deploys multi-tenant, configure um endpoint alcançável para a invalidação de cache, a rotação de credenciais e as atualizações de conexão chegarem ao Flowker. Omita-o apenas quando você aceita nenhuma entrega de evento de ciclo de vida e um cache por réplica dos validadores de requisição OpenAPI compilados. | — | Não | | `MULTI_TENANT_REDIS_PORT` | Porta do Redis | `6379` | Não | | `MULTI_TENANT_REDIS_PASSWORD` | Senha do Redis | — | Não | | `MULTI_TENANT_REDIS_TLS` | Habilita TLS na conexão com o Redis | `false` | Não | | `MULTI_TENANT_MAX_TENANT_POOLS` | Limite flexível de pools de conexão por tenant em cache. Sem definir, deixa a quantidade de pools sem limite. Recomendado: `100`. | — | Não | | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Quanto tempo um pool de tenant deve ficar ocioso antes de virar elegível à remoção (segundos). Recomendado: `300`. | — | Não | | `MULTI_TENANT_TIMEOUT` | Timeout das requisições ao Tenant Manager (segundos). Sem definir, deixa o cliente HTTP sem timeout. Recomendado: `30`. | — | Não | | `MULTI_TENANT_CACHE_TTL_SEC` | TTL do cache de configurações de tenant (segundos). Um valor positivo vale para o cache local de tenant e para o cache do cliente do Tenant Manager. Quando não definida ou não positiva, os padrões deles são `43200` segundos (12 horas) e `3600` segundos (1 hora), respectivamente. Recomendado: `120`. | `43200` local / `3600` cliente do Tenant Manager | Não | | `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Falhas consecutivas que abrem o circuito. Um único valor governa o breaker por configuração de provedor e o breaker do cliente HTTP do Tenant Manager. Sem definir, deixa o breaker por configuração de provedor em 20 e o breaker do Tenant Manager inativo, então defina-a explicitamente em deploys multi-tenant. | `20` (por configuração de provedor) | Não | | `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Timeout de recuperação do circuit breaker (segundos) | `30` | Não | ## Cache de tokens Limites do cache compartilhado de tokens OAuth 2.0 usado pela autenticação de provedores (fluxos OIDC e de endpoint de token OAuth2). | Variável | Descrição | Padrão | Obrigatório | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- | | `TOKEN_CACHE_MAX_TTL_SEC` | Tempo máximo em que um token em cache é confiável, independentemente do `expires_in` do provedor | `3600` | Não | | `TOKEN_CACHE_JANITOR_INTERVAL_SEC` | Com que frequência a rotina de limpeza em segundo plano remove os tokens expirados (segundos) | `300` | Não | | `TOKEN_CACHE_REFRESH_BUFFER_SEC` | Com quanta antecedência da expiração um token em cache é renovado de forma proativa (segundos) | `60` | Não | | `TOKEN_CACHE_TENANT_SCOPED_DISABLED` | Desliga o cache de tokens com escopo por tenant. O escopo por tenant é o padrão no modo multi-tenant; desligá-lo volta a compartilhar um único cache entre os tenants. | `false` | Não | ## Observabilidade | Variável | Descrição | Padrão | Obrigatório | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------- | | `ENABLE_TELEMETRY` | Habilita a instrumentação OpenTelemetry | `false` | Não | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do exportador OTLP | — | Sim (se `ENABLE_TELEMETRY=true`) | | `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço para a telemetria. Recomendado: `flowker`. | — | Não | | `OTEL_RESOURCE_SERVICE_VERSION` | Versão do serviço para a telemetria | — | Não | | `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Rótulo do ambiente de deploy | — | Não | | `OTEL_LIBRARY_NAME` | Nome da biblioteca de instrumentação. O logger exige esse nome em todo boot, inclusive quando `ENABLE_TELEMETRY` está em `false`. Recomendado: `flowker`. | — | Sim | | `SKIP_LIB_COMMONS_TELEMETRY` | Pula a telemetria da biblioteca commons | `false` | Não | | `LOG_LEVEL` | Nível de log (`debug`, `info`, `warn`, `error`, `dpanic`, `panic` ou `fatal`; sem diferenciar maiúsculas). Sem definir, o nível segue `ENV_NAME`: `development` e `local` logam em `debug`, todo outro valor loga em `info`. Um nível não reconhecido impede o servidor de iniciar. | — | Não | ## Segurança | Variável | Descrição | Padrão | Obrigatório | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | | `SSRF_ALLOW_PRIVATE` | Permite chamadas HTTP de executor para IPs privados. Apenas a string exata `true` habilita isso. Nunca habilite em produção. | `false` | Não | | `ALLOW_INSECURE_TLS` | Pula a exigência de TLS nos clientes de infraestrutura compartilhados e, em vez disso, registra um aviso no log. Aceita `true`, `1`, `yes` ou `on`. Deixe-a sem definir em produção para o TLS real continuar obrigatório. | `false` | Não | | `HTTP_MAX_BODY_BYTES` | Limite do corpo de requisição enviado e do corpo de resposta lido nas chamadas HTTP de saída aos provedores (bytes). Um valor zero ou negativo resolve para o padrão. | `10485760` (10 MiB) | Não | | `FAULT_INJECTION_ENABLED` | Habilita a injeção de falhas para testes | `false` | Não | ## Swagger | Variável | Descrição | Padrão | Obrigatório | | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | ----------- | | `SWAGGER_ENABLED` | Serve a spec OpenAPI gerada e a UI de documentação em `/openapi/openapi.json`, `/openapi/openapi.yaml` e `/openapi/docs` | `false` | Não | | `SWAGGER_TITLE` | Título da página da UI de documentação | — | Não |