Fundamentos da configuração 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 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.

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 e Saúde e prontidão.

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 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.

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:

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

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.

Visão geral

Fundamentos de integração

Estabilidade e qualidade

Fundamentos da configuração BYOC

Modo de implantação e TLS

Servidor

Datastores

Multi-tenancy

Configuração em tempo de execução

Streaming e outbox

Service discovery

Observabilidade

Autenticação de plugins

Variáveis por produto

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

​Modo de implantação e TLS

​Servidor

​Datastores

​Multi-tenancy

​Configuração em tempo de execução

​Streaming e outbox

​Service discovery

​Observabilidade

​Autenticação de plugins

​Variáveis por produto

Midaz

Tracer

Reporter

Flowker

Lender

Fetcher

Modo de implantação e TLS

Servidor

Datastores

Multi-tenancy

Configuração em tempo de execução

Streaming e outbox

Service discovery

Observabilidade

Autenticação de plugins

Variáveis por produto