> ## 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 de configuração do BYOC

> Variáveis de ambiente que se repetem entre os serviços Go da Lerian ao rodar BYOC na própria nuvem ou on-prem.

Em um deploy BYOC (bring your own cloud), você roda os produtos Lerian dentro da sua própria infraestrutura AWS, GCP ou on-prem. Você é dono dos dados e do runtime. Você configura cada serviço por meio de variáveis de ambiente, e a maioria delas é específica do serviço. Esta página cobre variáveis que se repetem entre os serviços Go da Lerian. Use a página de cada produto para o restante.

> [!NOTE]
>
> Estas variáveis não são a lista completa. Nomes e padrões de variável diferem entre os serviços, e os serviços adicionam suas próprias chaves. Veja [Variáveis por produto](#per-product-variables).

## Modo de deploy e TLS

| Variável | Descrição | Padrão | Valores permitidos |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Postura de deploy. O efeito, o padrão e os valores aceitos variam por serviço. | Varia por serviço | Varia por serviço |
| `ALLOW_INSECURE_TLS` | Contorna a exigência de TLS por conexão nas DSNs de infraestrutura. Destinado apenas ao desenvolvimento local. O [Pix JD](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#connections-without-tls) também a usa para aceitar endereços `http://` nas suas conexões de saída, em todo ambiente. | `false` | `true`, `false` |

> [!WARNING]
>
> Para um deploy BYOC em produção, defina `DEPLOYMENT_MODE=byoc`, conecte cada datastore por TLS e deixe `ALLOW_INSECURE_TLS` sem definir (`false`).

## Server

| Variável | Descrição | Padrão | Valores permitidos |
| - | - | - | - |
| `SERVER_ADDRESS` | Endereço de escuta HTTP principal (`host:port`, geralmente `:port`). As sondas usam essa mesma porta. | Varia por serviço | `host:port` |
| `LOG_LEVEL` | Verbosidade do log. Use `info` ou superior em produção. | Varia por serviço | `debug`, `info`, `warn`, `error` |
| `ENV_NAME` | Rótulo do ambiente. No SLC, é normalizado para uma allowlist. | Varia por serviço | SLC: `production`, `staging`, `uat`, `development`, `local` |

> [!NOTE]
>
> Alguns serviços expõem um `SERVER_PORT` numérico em vez de, ou junto com, `SERVER_ADDRESS`. Alguns componentes worker expõem uma porta de saúde dedicada (por exemplo `HEALTH_PORT` ou `WORKER_SERVER_PORT`). Veja [Portas de rede padrão](https://docs.lerian.studio/pt/reference/default-network-ports.md) e [Health and readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md).

## Datastores

Todo serviço que persiste estado se conecta a um ou mais datastores. O prefixo da variável depende do armazenamento 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. | Varia por serviço | Host / porta |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` | Credenciais de conexão. A senha é um segredo. Injete-a no momento do deploy e nunca faça commit dela. | Varia por serviço | 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 separa em namespace por banco de dados lógico como `DB_{MODULE}_NAME`. Consulte a página de cada produto. | Varia por serviço | String |
| `POSTGRES_SSLMODE` | Modo de TLS do libpq. Use `require` ou algo mais forte em produção. | Varia por serviço | `disable`, `require`, `verify-ca`, `verify-full` |
| `POSTGRES_REPLICA_*` | Conexão opcional de réplica de leitura (mesmo formato do primário). | — | Host / porta / credenciais |
| `MONGO_URI` / `MONGO_HOST` / `MONGO_PORT` | Conexão com o MongoDB, como 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). | Varia por serviço | `host:port` / segredo |
| `REDIS_TLS` / `REDIS_CA_CERT` | Habilita TLS para o Redis e fornece um certificado CA PEM codificado em base64. No SLC, `REDIS_TLS=true` exige um `REDIS_CA_CERT` não vazio. | `false` / — | `true`, `false` / PEM em base64 |
| `RABBITMQ_HOST` / `RABBITMQ_URI` | Host do broker e esquema de conexão. Use `amqps` em produção. | Varia por serviço | Host / `amqp`, `amqps` |
| `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS` | Credenciais do broker (a senha é um segredo). No SLC, quando o RabbitMQ está habilitado e a URL dele não tem credenciais, declare explicitamente `RABBITMQ_DEFAULT_USER` e `RABBITMQ_DEFAULT_PASS`. | — | String / segredo |

> [!NOTE]
>
> Nem todo serviço usa todo armazenamento, e os prefixos variam. O Midaz separa em namespace as conexões por banco de dados lógico (por exemplo `DB_ONBOARDING_*`, `DB_TRANSACTION_*`, `MONGO_CRM_*`).

## Configuração em runtime

| Variável | Descrição | Padrão | Valores permitidos |
| - | - | - | - |
| `SYSTEMPLANE_ENABLED` | Habilita a API admin de configuração em runtime do systemplane, nos serviços que expõem essa opção. Verifique a página de cada serviço. | Varia por serviço | `true`, `false` |

Quando habilitado, o serviço expõe um plano para leitura e escrita da configuração em runtime. Veja [Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) para a API e os namespaces.

## Streaming e outbox

Se a publicação de eventos vem ligada por padrão, e qual opção a controla, difere por serviço. Verifique a página de cada produto para o contrato dele, por exemplo [SPI](https://docs.lerian.studio/pt/rails/spi/spi-environment-variables.md#outbox-and-streaming) e [SILOC](https://docs.lerian.studio/pt/rails/siloc/siloc-environment-variables.md#observability).

| Variável | Descrição | Padrão | Valores permitidos |
| - | - | - | - |
| `STREAMING_ENABLED` | Habilita o produtor de eventos, nos serviços que expõem essa opção. | Varia por serviço | `true`, `false` |
| `STREAMING_BROKERS` | Brokers Kafka/RedPanda de bootstrap, como lista `host:port` separada por vírgulas. Obrigatória na inicialização nos serviços cujo streaming não tem modo desligado. | — | CSV de `host:port` |
| `STREAMING_CLOUDEVENTS_SOURCE` | O `source` do CloudEvents gravado em todo evento que o serviço emite. Vários produtos aceitam exatamente um literal e recusam iniciar com qualquer outro, então pegue o valor na página do próprio produto. | Varia por serviço | O literal que o produto exige |
| `STREAMING_EVENT_POLICIES` | Substituições de política de entrega por evento, como entradas `event.key.attribute=value` separadas por vírgulas, ponto e vírgula ou quebras de linha (por exemplo `transaction.created.enabled=true,transaction.created.outbox=always`). Os atributos são `enabled`, `direct`, `outbox` e `dlq`. Vazio mantém a política padrão de cada evento. | — | Lista `event.key.attribute=value` |
| `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` | Habilita o dispatcher do outbox transacional (quando o serviço o expõe separadamente). | Varia por serviço | `true`, `false` |

> [!NOTE]
>
> As variáveis que protegem a conexão com o broker variam por serviço. Alguns serviços leem `STREAMING_SASL_*` e `STREAMING_TLS_*`, e o [Consignado](https://docs.lerian.studio/pt/rails/consignado/consignado-environment-variables.md) lê `STREAMING_KAFKA_SASL_*` e `STREAMING_KAFKA_TLS_*`. Defina-as quando o seu broker exigir autenticação ou TLS, e pegue os nomes na página do próprio produto.

## Descoberta de serviços

Nos serviços que oferecem descoberta de serviços via Consul, ela vem desligada por padrão. Quando habilitada, o serviço se registra e resolve pares por meio do Consul em vez de endereços estáticos.

| Variável | Descrição | Padrão | Valores permitidos |
| - | - | - | - |
| `SD_ENABLED` | Habilita a descoberta de serviços via Consul. | `false` | `true`, `false` |
| `SD_EXTERNAL_ADDRESS` / `SD_INTERNAL_ADDRESS` | Endereços anunciados. Obrigatórios quando habilitado. | — | `host:port` |
| `SD_TLS` / `SD_TLS_SKIP_VERIFY` | Habilita TLS para o Consul e (separadamente) ignora a verificação de certificado. | `false` | `true`, `false` |
| `SD_TOKEN` | Token de ACL do Consul (segredo). | — | Segredo |

> [!NOTE]
>
> Alguns serviços usam aliases legados (`SD_ADVERTISE_*`, `CONSUL_ADDR`) para o mesmo comportamento.

## Observabilidade

A telemetria é push-based (OTLP). Alguns serviços também expõem um endpoint `/metrics` para scraping do Prometheus. Veja [Health and readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md).

| Variável | Descrição | Padrão | Valores permitidos |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Habilita a instrumentação OpenTelemetry. | `false` | `true`, `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. Use um endpoint `https://` em produção. | Varia por serviço | URL |
| `ALLOW_INSECURE_OTEL` | Permite que um serviço envie telemetria para um endpoint OTLP em texto puro (`http://` ou sem esquema) em produção. Sem ela, muitos serviços não iniciam com um endpoint em texto puro em produção. Use um motivo curto. Para manter o TLS obrigatório, deixe-a sem valor. | Sem valor | String |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço anexado à telemetria exportada. | Padrão do serviço | String |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Rótulo do ambiente anexado à telemetria exportada. | Varia por serviço | String |

## Autenticação de plugin

Os serviços Lerian podem autenticar rotas protegidas por meio do Access Manager (com Caradhras). O toggle de autenticação, o nome da variável e o padrão dele variam por serviço. Sempre habilite a autenticação em produção. Verifique a página de variáveis de ambiente de cada produto ou trilho para o nome oficial do toggle, o padrão dele 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 padrão variam por serviço. | Varia por serviço | `true`, `false` |
| `PLUGIN_AUTH_ADDRESS` / `PLUGIN_AUTH_HOST` / `AUTH_ADDRESS` | Endereço do serviço Access Manager. Obrigatório quando habilitado. | — | Endereço |

## Variáveis por produto

Cada produto adiciona as próprias variáveis: prefixos de datastore, URLs de integração, ajustes de worker e feature toggles. A página de cada produto traz a lista completa e atual, por exemplo:

> [card] [Midaz](https://docs.lerian.studio/pt/products/midaz/midaz-environment-variables.md)

> [card] [Tracer](https://docs.lerian.studio/pt/products/tracer/tracer-environment-variables.md)

> [card] [Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-environment-variables.md)

> [card] [Lender](https://docs.lerian.studio/pt/products/lender/configuration-and-deploy.md)


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