Variáveis de ambiente

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

Visão geral

Guias

Console

Operações

Variáveis de ambiente

Servidor

Deploy

Autenticação

Banco de dados (MongoDB)

Agendador

URLs dos serviços Lerian

Schema registry e validação XSD

Segredos

Emissão de token do Tenant Manager

Multi-tenant

Cache de tokens

Observabilidade

Segurança

Swagger

​Servidor

​Deploy

​Autenticação

​Banco de dados (MongoDB)

​Agendador

​URLs dos serviços Lerian

​Schema registry e validação XSD

​Segredos

​Emissão de token do Tenant Manager

​Multi-tenant

​Cache de tokens

​Observabilidade

​Segurança

​Swagger

Servidor

Deploy

Autenticação

Banco de dados (MongoDB)

Agendador

URLs dos serviços Lerian

Schema registry e validação XSD

Segredos

Emissão de token do Tenant Manager

Multi-tenant

Cache de tokens

Observabilidade

Segurança

Swagger