> ## 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.
# Fundamentos da configuração BYOC
> As variáveis de ambiente compartilhadas entre os serviços Go da Lerian, com seus valores possíveis — os botões de base que um operador ajusta ao implantar em sua própria infraestrutura de nuvem ou on-premises (BYOC).
Em uma implantação BYOC (bring your own cloud — traga sua própria nuvem), você executa os produtos Lerian dentro da sua própria infraestrutura AWS, GCP ou on-premises e é dono dos dados e do runtime. Cada serviço é configurado por variáveis de ambiente, e a maioria delas é específica do serviço. Esta página cobre a **base universal** — as variáveis que se comportam da mesma forma em todos os serviços Go da Lerian — para que você ajuste os botões de nível de implantação uma vez e então recorra à página de cada produto para o restante.
Esta é a base compartilhada, não a lista completa. Os prefixos das variáveis diferem ligeiramente entre os serviços (por exemplo, um serviço com bancos de dados separados de onboarding e de transação usa namespaces distintos para eles), e cada serviço adiciona suas próprias chaves. Veja [Variáveis por produto](#variáveis-por-produto) para as listas exaustivas.
## Modo de implantação e TLS
`DEPLOYMENT_MODE` define com que rigor o serviço impõe TLS em suas conexões de infraestrutura, e seu valor é refletido na resposta de [`/readyz`](/pt/reference/health-and-readiness).
| Variável | Descrição | Padrão | Valores permitidos |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------- |
| `DEPLOYMENT_MODE` | Postura de imposição de TLS. `local` permite conexões em texto puro. `byoc` recomenda TLS e alerta sobre texto puro, mas ainda inicializa. `saas` torna o TLS obrigatório — o serviço se recusa a iniciar se qualquer conexão de dependência não tiver TLS. | `local` | `local`, `byoc`, `saas` |
| `ALLOW_INSECURE_TLS` | Ignora a imposição de TLS por conexão nas DSNs de infraestrutura. Destinado apenas ao desenvolvimento local. | `false` | `true`, `false` |
Para uma implantação BYOC em produção, defina `DEPLOYMENT_MODE=byoc`, conecte cada datastore por TLS e deixe `ALLOW_INSECURE_TLS` sem definir (`false`). Os padrões de `local` entregam conexões em texto puro e não são seguros para produção.
## Servidor
| Variável | Descrição | Padrão | Valores permitidos |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------- |
| `SERVER_ADDRESS` | Endereço HTTP principal de escuta (`host:port`, normalmente `:port`). As sondas de liveness, readiness e versão ficam vinculadas a esta mesma porta. | Varia por serviço | `host:port` |
| `LOG_LEVEL` | Verbosidade dos logs. Use `info` ou superior em produção. | `debug` | `debug`, `info`, `warn`, `error` |
| `ENV_NAME` | Rótulo do ambiente. Alguns serviços ativam controles de segurança mais rígidos quando isto é definido como `production`. | `development` | String livre |
| `VERSION` | Tag de versão do serviço exposta por `/version`. | Por release | String semver |
Alguns serviços expõem um `SERVER_PORT` numérico em vez de, ou além de, `SERVER_ADDRESS`. Componentes worker sem uma API HTTP principal expõem uma porta de saúde dedicada (por exemplo `HEALTH_PORT` ou `WORKER_SERVER_PORT`). Veja [Portas de rede padrão](/pt/reference/default-network-ports) e [Saúde e prontidão](/pt/reference/health-and-readiness).
## Datastores
Todo serviço que persiste estado conecta-se a um ou mais datastores. O prefixo da variável depende do store — e, em alguns serviços, do banco de dados lógico. A tabela abaixo mostra o formato comum; consulte a página de cada produto para os nomes exatos.
| Variável | Descrição | Padrão | Valores permitidos |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------ |
| `POSTGRES_HOST` / `POSTGRES_PORT` | Host e porta do PostgreSQL. | — / `5432` | Host / porta |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` | Credenciais de conexão. A senha é um segredo — injete-a no momento da implantação, nunca faça commit dela. | — | String / segredo |
| `POSTGRES_NAME` / `POSTGRES_DB` / `DB_NAME` | Nome do banco de dados. A chave exata varia por serviço — `POSTGRES_NAME` (por exemplo, STA, SLC, SISBAJUD, Consignado), `POSTGRES_DB` (SPB, SPI, Boleto) ou `DB_NAME` (Pix Indireto); o Midaz a nomeia por banco de dados lógico como `DB_{MODULE}_NAME`. Consulte a página de cada produto. | — | String |
| `POSTGRES_SSLMODE` | Modo TLS do libpq. Use `require` ou mais forte em produção. | `disable` | `disable`, `require`, `verify-ca`, `verify-full` |
| `POSTGRES_REPLICA_*` | Conexão opcional com réplica de leitura (mesmo formato do primário). | — | Host / porta / credenciais |
| `MONGO_URI` / `MONGO_HOST` / `MONGO_PORT` | Conexão com o MongoDB, como uma URI completa ou host e porta separados. | — | String de conexão / host / porta |
| `MONGO_TLS_CA_CERT` | Certificado CA PEM codificado em Base64 para TLS (por exemplo, um serviço MongoDB gerenciado). | — | PEM em Base64 |
| `REDIS_HOST` / `REDIS_PASSWORD` | Endpoint do Redis/Valkey e senha de autenticação (segredo). | — | `host:port` / segredo |
| `REDIS_TLS` / `REDIS_CA_CERT` | Ativa o TLS para o Redis e fornece um CA PEM codificado em Base64. | `false` / — | `true`, `false` / PEM em Base64 |
| `RABBITMQ_HOST` / `RABBITMQ_URI` | Host do broker e esquema de conexão. Use `amqps` em produção. | — / `amqp` | Host / `amqp`, `amqps` |
| `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS` | Credenciais do broker (a senha é um segredo). | — | String / segredo |
Nem todo serviço usa todos os stores, e os prefixos variam: os produtos centrais costumam usar namespaces por banco de dados lógico nas conexões (por exemplo `DB_ONBOARDING_*`, `DB_TRANSACTION_*`, `MONGO_CRM_*`), enquanto plugins e trilhos usam o formato plano `POSTGRES_*` acima. No modo multi-tenant, as credenciais estáticas de datastore são ignoradas — as conexões são resolvidas por tenant (veja abaixo).
## Multi-tenancy
O multi-tenancy vem **desativado por padrão**. Quando você o ativa, cada conexão de datastore passa da configuração estática para a resolução por tenant através do Tenant Manager, e o serviço adiciona uma sonda de prontidão por tenant em `GET /readyz/tenant/{id}`.
| Variável | Descrição | Padrão | Valores permitidos |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------ |
| `MULTI_TENANT_ENABLED` | Ativa a resolução de conexão por tenant. Quando `false`, o serviço roda em single-tenant com as conexões estáticas acima. | `false` | `true`, `false` |
| `MULTI_TENANT_URL` | URL da API do Tenant Manager. Obrigatória quando ativado. | — | URL |
| `MULTI_TENANT_SERVICE_API_KEY` | Chave de API para o Tenant Manager (segredo). Obrigatória quando ativado. | — | Segredo |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | Permite uma URL `http://` em texto puro para o Tenant Manager. Nunca ative em produção — as credenciais trafegam em texto puro. | `false` | `true`, `false` |
| `MULTI_TENANT_REDIS_HOST` / `MULTI_TENANT_REDIS_PORT` | Endpoint Redis opcional para eventos de ciclo de vida de tenant (descoberta orientada a eventos). | — / `6379` | Host / porta |
Botões adicionais de dimensionamento de pool por tenant, circuit-breaker e TTL de cache (`MULTI_TENANT_MAX_TENANT_POOLS`, `MULTI_TENANT_CIRCUIT_BREAKER_*`, `MULTI_TENANT_CACHE_TTL_SEC`, entre outros) existem por serviço. Veja as páginas por produto.
## Configuração em tempo de execução
| Variável | Descrição | Padrão | Valores permitidos |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------ |
| `SYSTEMPLANE_ENABLED` | Ativa a API de administração de configuração em tempo de execução do systemplane na porta principal. Desativada por padrão na maioria dos serviços; alguns — por exemplo, o SPI — a ativam por padrão. Consulte a página de cada serviço. | `false` (SPI: `true`) | `true`, `false` |
Quando ativada, o serviço expõe um plano autenticado para ler e gravar configuração em tempo de execução. Veja [Systemplane](/pt/reference/systemplane/overview) para a API, os namespaces e as permissões exigidas.
## Streaming e outbox
O caminho de publicação de eventos (um produtor lib-streaming apoiado por um outbox transacional) vem **desativado por padrão** em todos os serviços, exceto no worker do Fetcher, que define `STREAMING_ENABLED=true` para emitir eventos de conclusão de job.
| Variável | Descrição | Padrão | Valores permitidos |
| ------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------- |
| `STREAMING_ENABLED` | Ativa o produtor de eventos. | `false` (worker do Fetcher: `true`) | `true`, `false` |
| `STREAMING_BROKERS` | Brokers de bootstrap Kafka/RedPanda, como uma lista `host:port` separada por vírgulas. | — | CSV de `host:port` |
| `STREAMING_COMPRESSION` | Codec de compressão do produtor. | `lz4` | `none`, `gzip`, `snappy`, `lz4`, `zstd` |
| `STREAMING_REQUIRED_ACKS` | Nível de confirmação do produtor. | `all` | `all`, `leader`, `none` |
| `OUTBOX_ENABLED` | Ativa o dispatcher do outbox transacional (onde o serviço o expõe separadamente). | `false` | `true`, `false` |
`STREAMING_SASL_*` e `STREAMING_TLS_*` protegem a conexão com o broker — defina-as quando seu broker exigir autenticação ou TLS.
## Service discovery
O service discovery via Consul vem **desativado por padrão**. Quando ativado, o serviço se registra e resolve os peers através do Consul em vez de endereços estáticos.
| Variável | Descrição | Padrão | Valores permitidos |
| --------------------------------------------- | -------------------------------------------------------------------------------- | ------- | ------------------ |
| `SD_ENABLED` | Ativa o service discovery via Consul. | `false` | `true`, `false` |
| `SD_ADDRESS` | Endereço do agente Consul. Obrigatório quando ativado. | — | `host:port` |
| `SD_EXTERNAL_ADDRESS` / `SD_INTERNAL_ADDRESS` | Endereços anunciados. Obrigatórios quando ativado. | — | `host:port` |
| `SD_TLS` / `SD_TLS_SKIP_VERIFY` | Ativa o TLS para o Consul e (separadamente) ignora a verificação de certificado. | `false` | `true`, `false` |
| `SD_TOKEN` | Token ACL do Consul (segredo). | — | Segredo |
Alguns serviços usam aliases legados (`SD_ADVERTISE_*`, `CONSUL_ADDR`) para o mesmo comportamento.
## Observabilidade
A telemetria é baseada em push (OTLP). Alguns serviços expõem adicionalmente um endpoint `/metrics` para scraping pelo Prometheus — veja [Saúde e prontidão](/pt/reference/health-and-readiness).
| Variável | Descrição | Padrão | Valores permitidos |
| -------------------------------------- | ----------------------------------------------------------------------- | ----------------- | ------------------ |
| `ENABLE_TELEMETRY` | Ativa a instrumentação OpenTelemetry. | `false` | `true`, `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. Obrigatório quando a telemetria está ativada. | — | URL |
| `OTEL_EXPORTER_OTLP_PORT` | Porta OTLP, ao usar host e porta separados. | `4317` | Porta |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço anexado à telemetria exportada. | Padrão do serviço | String |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Rótulo de ambiente anexado à telemetria exportada. | — | String |
| `OTEL_INSECURE_EXPORTER` | Permite uma conexão OTLP em texto puro. Deixe `false` em produção. | `false` | `true`, `false` |
## Autenticação de plugins
Os serviços Lerian podem autenticar as rotas protegidas — incluindo a API de administração do systemplane — através do Access Manager (baseado em Casdoor). O toggle de autenticação, seu nome de variável e seu valor padrão diferem por serviço: a maioria dos plugins e produtos usa `PLUGIN_AUTH_ENABLED` (padrão `false`, desligado), enquanto rails nativos como SILOC e SPB usam `AUTH_ENABLED` (padrão `true`, ligado — obrigatório em produção e SaaS) em conjunto com `AUTH_ADDRESS`. Sempre ative a autenticação em produção e consulte a página de variáveis de ambiente de cada produto ou rail para o nome do toggle, o valor padrão e as rotas que ele protege.
| Variável | Descrição | Padrão | Valores permitidos |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ------------------ |
| `PLUGIN_AUTH_ENABLED` / `AUTH_ENABLED` | Exige autenticação do Access Manager nas rotas protegidas. O nome e o valor padrão variam por serviço — plugins usam `PLUGIN_AUTH_ENABLED`, rails nativos usam `AUTH_ENABLED`. | Plugins `false`, rails `true` | `true`, `false` |
| `PLUGIN_AUTH_ADDRESS` / `PLUGIN_AUTH_HOST` / `AUTH_ADDRESS` | Endereço do serviço Access Manager. Obrigatório quando ativado. | — | Endereço |
## Variáveis por produto
As variáveis acima são a base compartilhada. Cada produto adiciona as suas próprias — prefixos de datastore, URLs de integração, ajuste de workers e chaves de recurso. Use as páginas por produto para a lista completa e atual:
A lista exaustiva de variáveis por serviço é entregue no arquivo `.env.example` de cada serviço. Trate-o como a fonte da verdade para um release específico e nunca faça commit de valores de segredo reais nele.