> ## 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: servidor, autenticação, MongoDB, scheduler, URLs dos provedores nativos, registro de schemas, ingresso do Streaming Hub, cache de tokens, observabilidade e limites.

Esta referência lista as variáveis de ambiente que configuram o Flowker.

A coluna **Padrão** mostra o valor que o Flowker aplica quando você não define uma variável. Um traço significa que o Flowker não aplica nenhum valor próprio. A coluna **Obrigatório** marca as variáveis sem as quais o servidor não inicia. Uma variável marcada como **Sensível** carrega uma credencial.

O Flowker tem dois binários. O binário da API atende a API HTTP. O binário do worker executa o scheduler que dispara os workflows com gatilho `schedule`. Uma variável que se aplica a um só binário informa qual.

## Servidor

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENV_NAME` | Ambiente do deploy: `production`, `staging`, `uat`, `development` ou `local`. Qualquer outro valor impede o servidor de iniciar. Com `production`, `PLUGIN_AUTH_ENABLED`, `XSD_SCHEMAS_AUTH_ENABLED` e `OPENAPI_SCHEMAS_AUTH_ENABLED` precisam ser `true`, ou o servidor não inicia. | — | Sim |
| `SERVER_ADDRESS` | Endereço de escuta do binário da API, por exemplo `:4021`. | — | Não |
| `WORKER_SERVER_ADDRESS` | Endereço de escuta do binário do worker. | `:4022` | Não |
| `CORS_ALLOWED_ORIGINS` | Origens, separadas por vírgula, permitidas em requisições cross-origin. | — | Não |
| `TRUSTED_PROXIES` | Faixas CIDR, separadas por vírgula, dos seus balanceadores de carga ou do seu ingress. O Flowker lê o IP do cliente em `X-Forwarded-For` apenas quando a requisição passa por uma dessas faixas. O Access Manager verifica a lista de IPs permitidos contra esse IP do cliente. Uma entrada que não é uma faixa CIDR impede o servidor de iniciar. | — | Não |
| `PPROF_ENABLED` | Atende dados de profiling do Go em `/debug/pprof/` em `127.0.0.1:6060`, apenas no binário do worker. | `false` | Não |

## Deploy

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Modo de deploy. Com `saas`, `MONGO_URI` precisa usar `mongodb+srv://` ou trazer `tls=true` ou `ssl=true`, ou o servidor não inicia. Quando ela não está definida, `/readyz` informa `local`. | — | Não |

## Autenticação

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Exige autenticação do Access Manager nas rotas de workflow, de webhook e de gestão. Com `false`, essas rotas não exigem um token. | `false` | Não |
| `PLUGIN_AUTH_ADDRESS` | Endereço do Access Manager. O Flowker também obtém dele o endpoint de token dos provedores nativos, com `/v1/login/oauth/access_token` acrescentado ao final. | — | Quando `PLUGIN_AUTH_ENABLED=true` |
| `XSD_SCHEMAS_AUTH_ENABLED` | Com `true`, as rotas `/v1/xsd-schemas` seguem `PLUGIN_AUTH_ENABLED`. Com `false`, elas não exigem um token. Um valor não definido ou não reconhecido conta como `true`. | `true` | Não |
| `OPENAPI_SCHEMAS_AUTH_ENABLED` | Com `true`, as rotas `/v1/openapi-schemas` seguem `PLUGIN_AUTH_ENABLED`. Com `false`, elas não exigem um token. Um valor não definido ou não reconhecido conta como `true`. | `true` | Não |

## MongoDB

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `MONGO_URI` | URI de conexão do MongoDB. Sensível. | — | Sim |
| `MONGO_DB_NAME` | Nome do banco de dados do MongoDB. | — | Sim |
| `MONGO_MAX_POOL_SIZE` | Tamanho máximo do pool de conexões do MongoDB. Um valor não definido, ou um valor igual ou menor que zero, mantém o padrão do driver do MongoDB. | — | Não |
| `MONGO_TLS_CA_CERT` | Certificado de CA em PEM, codificado em Base64, para a conexão TLS com o MongoDB. | — | Não |

## Scheduler e Redis

O binário do worker executa o scheduler. Os dois binários se conectam ao Redis pelas variáveis `REDIS_*`. O worker usa o Redis para a fila do scheduler, e o binário da API o usa para enfileirar a execução de uma ocorrência estacionada.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SCHEDULER_ENABLED` | Liga ou desliga o scheduler. Um valor não definido ou não reconhecido conta como `true`. O binário do worker não inicia quando o valor é `false`. | `true` | Não |
| `REDIS_HOST` | Host do Redis. Quando o scheduler está ligado e o host está vazio, o binário do worker não inicia. O binário da API então responde às rotas de agendamento com `FLK-0763`. | — | Quando `SCHEDULER_ENABLED=true` |
| `REDIS_PORT` | Porta do Redis. | `6379` | Não |
| `REDIS_PASSWORD` | Senha do Redis. Sensível. | — | Binário do worker, quando `SCHEDULER_ENABLED=true` e `DEPLOYMENT_MODE=saas` |
| `REDIS_TLS` | Usa TLS na conexão com o Redis. | `false` | Não |
| `REDIS_DB` | Índice lógico do banco de dados do Redis. | `0` | Não |
| `SCHEDULER_CONCURRENCY` | Número máximo de execuções agendadas que o worker processa ao mesmo tempo. Um valor igual ou menor que zero conta como `10`. | `10` | Não |

## URLs dos provedores nativos

O Flowker lê a URL base de cada provedor nativo destas variáveis em vez da configuração de provedor armazenada. Quando uma variável está vazia, o Flowker usa o valor da configuração armazenada.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `MIDAZ_BASE_URL` | URL base do provedor `ledger`. É a URL base de transações e a URL base 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` | IDs, separados por vírgula, dos provedores nativos que o Flowker monta a partir da especificação OpenAPI publicada de cada um. Vazio deixa todos os provedores nativos disponíveis. O Flowker ignora um ID desconhecido. | — | Não |

## Registro de schemas e validação XSD

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SCHEMA_REGISTRY_S3_BUCKET` | Bucket S3 que armazena o conteúdo dos schemas XSD e OpenAPI. O Flowker inicia sem ele, mas as operações que leem ou gravam conteúdo de schema falham. | — | Não |
| `SCHEMA_REGISTRY_S3_REGION` | Região AWS do bucket. Quando ela está vazia, a região vem da configuração padrão da AWS. | — | Não |
| `SCHEMA_REGISTRY_CACHE_TTL_SEC` | Tempo de vida do cache de especificações de provedor já interpretadas, em segundos. | `300` | Não |
| `XSD_VALIDATOR_URL` | URL base do validador XSD. Vazio desliga a validação de schema XML. A URL precisa usar `https`, ou `http` com `XSD_VALIDATOR_ALLOW_INSECURE_HTTP=true`. Qualquer outra URL impede o servidor de iniciar. | — | Não |
| `XSD_VALIDATOR_ALLOW_INSECURE_HTTP` | Aceita um valor `http://` em `XSD_VALIDATOR_URL`. Apenas o valor `true`, em maiúsculas ou minúsculas, a liga. | `false` | Não |

## Ingresso do Streaming Hub

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `HUB_WEBHOOK_ENABLED` | Atende a rota assinada do Streaming Hub em `/v1/hub/webhooks/`. Com `true`, o servidor não inicia sem o armazenamento de credenciais que guarda cada segredo de assinatura. | `false` | Não |
| `HUB_WEBHOOK_TOLERANCE_SEC` | Janela de validade da assinatura de uma entrega, em segundos. Um valor igual ou menor que zero conta como o padrão. | `300` | Não |

## Cache de tokens de provedor

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `TOKEN_CACHE_MAX_TTL_SEC` | Tempo máximo durante o qual o Flowker confia em um token de provedor em cache, em segundos, qualquer que seja o `expires_in` que o provedor retorna. | `3600` | Não |
| `TOKEN_CACHE_JANITOR_INTERVAL_SEC` | Intervalo em que o Flowker apaga do cache os tokens expirados, em segundos. | `300` | Não |
| `TOKEN_CACHE_REFRESH_BUFFER_SEC` | Tempo antes da expiração em que o Flowker obtém um novo token, em segundos. Quando ela não está definida, vale a janela de renovação de cada provedor. | — | Não |

## Observabilidade

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Liga a exportação OpenTelemetry. | `false` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do exportador OTLP. | — | Quando `ENABLE_TELEMETRY=true` |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço na telemetria e no campo `service` de `/version`. | `flowker` | Não |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Rótulo do ambiente de deploy na telemetria. | — | Não |
| `OTEL_LIBRARY_NAME` | Nome da biblioteca de instrumentação. O logger a exige, também quando `ENABLE_TELEMETRY` é `false`. | — | Sim |
| `LOG_LEVEL` | Nível de log: `debug`, `info`, `warn`, `error`, `dpanic`, `panic` ou `fatal`. Quando ela não está definida, `development` e `local` registram em `debug`, e todos os outros ambientes registram em `info`. Um nível não reconhecido impede o servidor de iniciar. | — | Não |
| `SKIP_LIB_COMMONS_TELEMETRY` | Remove o middleware de telemetria das rotas HTTP. | `false` | Não |

## Limites e configurações de teste

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `HTTP_MAX_BODY_BYTES` | Maior corpo de requisição que o Flowker envia a um provedor, e maior corpo de resposta que ele lê de um provedor, em bytes. Um valor igual ou menor que zero conta como o padrão. | `10485760` (10 MiB) | Não |
| `SSRF_ALLOW_PRIVATE` | Permite que as chamadas HTTP a provedores alcancem endereços IP privados. Apenas o valor exato `true` a liga. | `false` | Não |
| `FAULT_INJECTION_ENABLED` | Responde com uma falha simulada a uma requisição que traz o header `X-Test-Fault-Injection`. | `false` | Não |

## Documentação OpenAPI

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SWAGGER_ENABLED` | Atende a especificação OpenAPI e a interface de documentação em `/openapi/openapi.json`, `/openapi/openapi.yaml` e `/openapi/docs`. | `false` | Não |
| `SWAGGER_TITLE` | Título da página da interface de documentação. | — | Não |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.