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 uma variável não está definida. Um traço significa que o Flowker não aplica nenhum valor de reserva: defina a variável explicitamente, usando o valor recomendado na descrição. A coluna Obrigatória marca as variáveis cuja ausência impede a inicialização do servidor. O Flowker é distribuído em dois binários. O binário de API serve a API HTTP. O binário worker executa o scheduler que dispara os workflows com trigger schedule e serve apenas /health e /readyz. As variáveis que se aplicam a um único binário indicam isso.

Servidor

Variável	Descrição	Padrão	Obrigatória
`ENV_NAME`	Nome do ambiente. Defina um entre `production`, `staging`, `uat`, `development` ou `local` — qualquer outro valor, inclusive um vazio, impede a inicialização do servidor. `production` ativa as proteções de produção: a autenticação de requisições, a de schemas XSD e a de schemas OpenAPI precisam estar habilitadas ou o servidor não inicia. Recomendado: `production` em produção e `development` nos demais ambientes.	—	Sim
`SERVER_ADDRESS`	Endereço de escuta do binário de API. Quando vazio, o Fiber faz bind 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 `/health` e `/readyz` do binário worker. Precisa ser diferente de `SERVER_ADDRESS` para que os dois binários rodem no mesmo host.	`:4022`	Não
`VERSION`	String de versão reportada pelo `/readyz`.	`dev`	Não
`CORS_ALLOWED_ORIGINS`	Lista separada por vírgulas de origens CORS permitidas. Vazio significa que nenhum acesso cross-origin é permitido (padrão restritivo).	—	Não
`TRUSTED_PROXIES`	Faixas CIDR separadas por vírgula dos proxies confiáveis (as sub-redes do seu load balancer/ingress). Quando definido, o `X-Forwarded-For` só é confiado 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 IP-allowlist. As entradas devem usar notação CIDR; um IP sem máscara falha na inicialização. Vazio mantém o recurso desligado.	—	Não

Deploy

Variável	Descrição	Padrão	Obrigatória
`DEPLOYMENT_MODE`	Modalidade de 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 TLS no bootstrap. Os providers de fixture são expostos quando `DEPLOYMENT_MODE` é resolvido como `local` após remover espaços e comparar sem diferenciar maiúsculas de minúsculas, desde que o ambiente não seja de produção. O `/readyz` reporta `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ória
`PLUGIN_AUTH_ENABLED`	Habilitar autenticação via plugin do Access Manager. Quando `false`, as rotas de workflow, webhook e gestão não exigem autenticação (apenas para desenvolvimento local). Com um `ENV_NAME` de produção, `false` impede a inicialização do servidor.	`false`	Não
`PLUGIN_AUTH_ADDRESS`	Endereço do serviço Access Manager. O endpoint de token machine-to-machine é derivado dele acrescentando `/v1/login/oauth/access_token`.	—	Sim (se `PLUGIN_AUTH_ENABLED=true`)
`XSD_SCHEMAS_AUTH_ENABLED`	Exigir autenticação nas rotas `/v1/xsd-schemas`. Um valor ausente ou não reconhecido é resolvido como `true`. Com um `ENV_NAME` de produção, `false` impede a inicialização do servidor.	`true`	Não
`OPENAPI_SCHEMAS_AUTH_ENABLED`	Exigir autenticação nas rotas `/v1/openapi-schemas`. Um valor ausente ou não reconhecido é resolvido como `true`. Com um `ENV_NAME` de produção, `false` impede a inicialização do servidor.	`true`	Não

Banco de dados (MongoDB)

Variável	Descrição	Padrão	Obrigatória
`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 (ex: AWS DocumentDB)	—	Não

Scheduler

O scheduler dispara os workflows com trigger schedule. Ele roda no binário worker e usa a própria configuração de Redis, separada da configuração de Redis multi-tenant. A inicialização não força essa separação: aponte o scheduler para a própria instância de Redis ou, no mínimo, para um índice de banco lógico diferente do usado pelos eventos de ciclo de vida de tenants.

Variável	Descrição	Padrão	Obrigatória
`SCHEDULER_ENABLED`	Interruptor geral do scheduler. Um valor ausente ou não reconhecido é resolvido como `true`; qualquer valor booleano válido que seja resolvido como `false` (por exemplo, `false`, `0` ou `f`) o desativa. O binário worker não inicia enquanto estiver em `false`.	`true`	Não
`SCHEDULER_REDIS_HOST`	Host do Redis dedicado do scheduler. A fila do scheduler vive nele, então defina-o onde quer que o scheduler esteja habilitado: sem host, o binário worker não inicia e nenhum workflow agendado dispara.	—	Sim (se `SCHEDULER_ENABLED=true`)
`SCHEDULER_REDIS_PORT`	Porta do Redis do scheduler	`6379`	Não
`SCHEDULER_REDIS_PASSWORD`	Senha do Redis do scheduler. Só é obrigatória quando um worker inicia o scheduler habilitado com `DEPLOYMENT_MODE=saas`; a inicialização apenas da API não valida esta variável.	—	Sim (worker; se `SCHEDULER_ENABLED=true` e `DEPLOYMENT_MODE=saas`)
`SCHEDULER_REDIS_TLS`	Habilitar TLS para a conexão com o Redis do scheduler. Defina `true` em produção e aponte o scheduler para um Redis que termine TLS.	`false`	Não
`SCHEDULER_REDIS_DB`	Índice de banco lógico do Redis para a fila. Mantenha-o distinto do índice de eventos de tenants.	`0`	Não
`SCHEDULER_CONCURRENCY`	Limite de concorrência de workers do servidor de consumo do scheduler. Um valor não positivo é resolvido como `10`.	`10`	Não

URLs de serviços Lerian

Os providers internos resolvem sua URL base a partir do ambiente, pela convenção {PROVIDER}_BASE_URL, em vez de tomá-la da configuração de provider armazenada. Deixe uma variável vazia para usar o valor do documento de configuração armazenado.

Variável	Descrição	Padrão	Obrigatória
`MIDAZ_BASE_URL`	URL base do provider `ledger`. Alimenta tanto a URL base de transações quanto a de onboarding.	—	Não
`TRACER_BASE_URL`	URL base do provider `tracer`	—	Não
`CRM_BASE_URL`	URL base do provider `crm`	—	Não
`FEES_BASE_URL`	URL base do provider `fees`	—	Não
`IDENTITY_BASE_URL`	URL base do provider `identity`	—	Não
`AUTH_BASE_URL`	URL base do provider `auth`	—	Não
`OPENAPI_NATIVE_PROVIDERS`	Lista separada por vírgulas de ids de providers nativos elegíveis para síntese a partir da especificação OpenAPI publicada. Vazio torna todos os providers nativos elegíveis; uma lista não vazia restringe a elegibilidade aos ids indicados.	—	Não

Registro de schemas e validação XSD

Variável	Descrição	Padrão	Obrigatória
`SCHEMA_REGISTRY_S3_BUCKET`	O armazenamento S3 é opcional para a inicialização. Se o bucket estiver vazio, o Flowker inicia com um caminho de metadados no MongoDB, mas as operações de conteúdo de schemas XSD e OpenAPI falham no uso; configure um bucket para ter um registro de schemas funcional.	—	Não
`SCHEMA_REGISTRY_S3_REGION`	Fixa a região AWS do bucket do registro de schemas. Vazio resolve a região pela cadeia padrão do SDK da AWS (`AWS_REGION` ou a configuração compartilhada).	—	Não
`SCHEMA_REGISTRY_CACHE_TTL_SEC`	TTL do cache de especificações parseadas que sustenta o resolvedor de schemas de saída nativos (segundos). Uma mudança em especificação publicada é capturada no próximo download cujo ETag seja diferente, independentemente do TTL.	`300`	Não
`XSD_VALIDATOR_URL`	URL base do sidecar validador XSD (ex: `http://xsd-validator:8081`). Deixe vazia para operar sem validação de schemas XML.	—	Não
`XSD_VALIDATOR_ALLOW_INSECURE_HTTP`	Um `true` após remover espaços e sem diferenciar maiúsculas de minúsculas habilita `http://` sem criptografia para `XSD_VALIDATOR_URL`; `1`, `t` e `yes` não.	`false`	Não

Segredos

Variável	Descrição	Padrão	Obrigatória
`FLOWKER_SECRETS_BACKEND`	Backend que resolve as credenciais de integrações externas. `tenant-manager` seleciona o leitor do AWS Secrets Manager; sem definir, a resolução de segredos fica desativada. Qualquer outro valor impede a inicialização do servidor.	—	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 ao ler credenciais do armazenamento do Tenant Manager. Precisa coincidir com `WORKOS_TM_SERVICE_NAME` para que o caminho de leitura e o de escrita resolvam a mesma identidade de serviço.	`flowker`	Não

Emissão de token do Tenant Manager

O Flowker emite um token bearer com escopo de plataforma para chamar os endpoints de escrita do Tenant Manager. A emissão de tokens exige definir juntas WORKOS_TM_TOKEN_URL, WORKOS_TM_CLIENT_ID e WORKOS_TM_CLIENT_SECRET. WORKOS_TM_SCOPE é opcional, mas um valor não vazio exige essas três variáveis de credenciais. WORKOS_TM_SERVICE_NAME apenas substitui o nome do serviço. Deixe a URL de token, o client ID, o client secret e o scope sem definir para desativar a emissão. Uma configuração parcial impede a inicialização do servidor. A URL base do Tenant Manager vem de MULTI_TENANT_URL.

Variável	Descrição	Padrão	Obrigatória
`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 para o grant `client_credentials`	—	Sim (as três, ou nenhuma)
`WORKOS_TM_CLIENT_SECRET`	Client secret para o grant `client_credentials`. Injete-o pelo seu gerenciador de segredos; ele nunca é escrito em logs.	—	Sim (as três, ou nenhuma)
`WORKOS_TM_SCOPE`	Escopo, delimitado por espaços, solicitado com o grant. Defini-lo sozinho, sem as três credenciais, impede a inicialização do servidor.	—	Não
`WORKOS_TM_SERVICE_NAME`	Nome do serviço Flowker como o Tenant Manager o conhece. Precisa coincidir com `FLOWKER_SECRETS_APPLICATION_NAME`.	`flowker`	Não

Multi-tenant

Quando MULTI_TENANT_ENABLED=true, as conexões com banco de dados são resolvidas por tenant através do Tenant Manager. Quando false (padrão), o Flowker opera em modo single-tenant com conexões estáticas.

Variável	Descrição	Padrão	Obrigatória
`MULTI_TENANT_ENABLED`	Habilitar a resolução de conexões 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`	API key para o endpoint de settings do Tenant Manager	—	Sim (se `MULTI_TENANT_ENABLED=true`)
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	Permitir uma URL do Tenant Manager em `http://` sem criptografia. Nunca habilite em produção — as credenciais trafegam em texto puro.	`false`	Não
`MULTI_TENANT_REDIS_HOST`	Host do Redis para eventos de ciclo de vida de tenants. Em implantações multi-tenant, configure um endpoint acessível para que a invalidação de cache, a rotação de credenciais e as atualizações de conexões cheguem ao Flowker. Omita-o somente se aceitar não receber eventos de ciclo de vida e usar um cache por réplica para validadores de requisições 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`	Habilitar TLS para a 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, o número de pools fica ilimitado. Recomendado: `100`.	—	Não
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	Quanto tempo um pool de tenant precisa ficar inativo antes de se tornar elegível para remoção (segundos). Recomendado: `300`.	—	Não
`MULTI_TENANT_TIMEOUT`	Timeout de requisição ao Tenant Manager (segundos). Sem definir, o cliente HTTP fica sem timeout. Recomendado: `30`.	—	Não
`MULTI_TENANT_CACHE_TTL_SEC`	TTL do cache de configurações de tenants (segundos). Um valor positivo se aplica ao cache local de tenants e ao cache do cliente Tenant Manager. Quando ausente ou não positivo, os padrões são `43200` segundos (12 horas) e `3600` segundos (1 hora), respectivamente. Recomendado: `120`.	`43200` local / `3600` cliente Tenant Manager	Não
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	Falhas consecutivas que abrem o circuito. Um mesmo valor governa o circuit breaker por configuração de provider e o do cliente HTTP do Tenant Manager. Sem definir, o breaker por configuração de provider fica em 20 e o do Tenant Manager fica inativo, então defina-o explicitamente em deploys multi-tenant.	`20` (por configuração de provider)	Não
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	Timeout de recuperação do circuit breaker (segundos)	`30`	Não

Cache de tokens

Limites para o cache compartilhado de tokens OAuth 2.0 usado pela autenticação de providers (fluxos OIDC e OAuth2 token-endpoint).

Variável	Descrição	Padrão	Obrigatória
`TOKEN_CACHE_MAX_TTL_SEC`	Tempo máximo em que qualquer token em cache é confiável, independentemente do `expires_in` do provider	`3600`	Não
`TOKEN_CACHE_JANITOR_INTERVAL_SEC`	Frequência com que o processo de limpeza em segundo plano remove tokens expirados (segundos)	`300`	Não
`TOKEN_CACHE_REFRESH_BUFFER_SEC`	Quanto antes da expiração um token em cache é renovado proativamente (segundos)	`60`	Não
`TOKEN_CACHE_TENANT_SCOPED_DISABLED`	Desativar o escopo por tenant do cache de tokens. O escopo por tenant é o padrão no modo multi-tenant; desativá-lo volta a compartilhar um único cache entre tenants.	`false`	Não

Observabilidade

Variável	Descrição	Padrão	Obrigatória
`ENABLE_TELEMETRY`	Habilitar 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 telemetria. Recomendado: `flowker`.	—	Não
`OTEL_RESOURCE_SERVICE_VERSION`	Versão do serviço para telemetria	—	Não
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Label de ambiente de deploy	—	Não
`OTEL_LIBRARY_NAME`	Nome da biblioteca de instrumentação. O logger a exige em toda inicialização, mesmo quando `ENABLE_TELEMETRY` é `false`. Recomendado: `flowker`.	—	Sim
`SKIP_LIB_COMMONS_TELEMETRY`	Ignorar 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 de minúsculas). Sem definir, o nível segue o `ENV_NAME`: `development` e `local` registram em `debug`, e qualquer outro valor registra em `info`. Um nível não reconhecido impede a inicialização do servidor.	—	Não

Segurança

Variável	Descrição	Padrão	Obrigatória
`SSRF_ALLOW_PRIVATE`	Permitir chamadas HTTP de executors para IPs privados. Apenas a string exata `true` o habilita. Nunca habilite em produção.	`false`	Não
`ALLOW_INSECURE_TLS`	Ignorar a exigência de TLS nos clientes de infraestrutura compartilhados e registrar um aviso no lugar. Aceita `true`, `1`, `yes` ou `on`. Deixe sem definir em produção para que o TLS continue obrigatório.	`false`	Não
`HTTP_MAX_BODY_BYTES`	Limite do corpo da requisição enviada e do corpo da resposta lida nas chamadas HTTP de saída para providers (bytes). Um valor zero ou negativo é resolvido para o padrão.	`10485760` (10 MiB)	Não
`FAULT_INJECTION_ENABLED`	Habilitar injeção de falhas para testes	`false`	Não

Swagger

Variável	Descrição	Padrão	Obrigatória
`SWAGGER_ENABLED`	Servir a especificação 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)

Scheduler

URLs de serviços Lerian

Registro de schemas 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)

​Scheduler

​URLs de serviços Lerian

​Registro de schemas 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)

Scheduler

URLs de serviços Lerian

Registro de schemas e validação XSD

Segredos

Emissão de token do Tenant Manager

Multi-tenant

Cache de tokens

Observabilidade

Segurança

Swagger