> ## 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
> Variáveis de ambiente para fazer o deploy e operar o Pix Lerian: identidade, bancos de dados, integrações, conectividade e eventos.
O Pix Lerian é formado pelos domínios SPI, DICT e COB e pelo adaptador de conectividade. A equipe de DevOps configura o comportamento dele por variáveis de ambiente no momento do deploy. Esta página cobre as variáveis **específicas desta interface**. Para os parâmetros compartilhados de servidor, telemetria, autenticação, streaming e service discovery, veja a [referência de configuração BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito marca uma variável que você deve definir no contexto descrito. `—` significa que não há padrão. `🔒` marca um **segredo**. Injete o valor no momento do deploy a partir do seu cofre de segredos e nunca faça commit dele.
## Como o `values.yaml` e o Systemplane funcionam juntos
No deploy inicial, os clientes fornecem a configuração pelo `values.yaml` do Helm chart entregue com a release. Depois da inicialização, as chaves de tempo de execução são gerenciadas pelo Systemplane.
O chart transforma os valores em variáveis de ambiente do pod:
| Tipo | Local no `values.yaml` | Comportamento |
| ------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Configuração de deploy | `.configmap.` | O Helm renderiza a configuração, e o Deployment injeta as chaves como variáveis de ambiente. |
| Segredo | Configuração de Secret do componente | Injete o valor no momento do deploy a partir do cofre de segredos e nunca faça commit dele. |
| Seed de tempo de execução | `spiSystemplane`, `dictSystemplane` ou `cobSystemplane` | Defina a variável no bloco de Systemplane dono do domínio. O componente usa o valor para inicializar a configuração de tempo de execução. |
Cada domínio tem um componente dedicado de Systemplane. O fluxo é:
O Helm cria o ConfigMap de cada componente e referencia o Secret dele. O Deployment carrega os dois com `envFrom` quando o pod sobe.
O componente de Systemplane lê as variáveis de ambiente mapeadas e aplica um seed apenas enquanto o valor armazenado ainda é igual ao padrão registrado. Um override administrativo existente não é sobrescrito.
As APIs de domínio e os workers leem o armazenamento do Systemplane. A definição de cada chave determina se ela aceita atualizações em tempo de execução ou exige um reinício.
Para as variáveis de bootstrap, atualize o `values.yaml`, rode o upgrade e faça o rollout do componente. Depois da inicialização, mude as chaves de tempo de execução pelo Systemplane. Mudar apenas o `values.yaml` não substitui um override armazenado.
* **Variáveis de ambiente de bootstrap direto:** `APPLICATION_NAME`, `SERVER_ADDRESS`, `DATABASE_URL`, `SYSTEMPLANE_POSTGRES_DSN`, `SYSTEMPLANE_SECRET_MASTER_KEY`, `VALKEY_URL`, `LICENSE_KEY`, `ORGANIZATION_IDS`, `SWAGGER_ENABLED`, `RABBITMQ_ENABLED`, `RABBITMQ_URI` e `STREAMING_*`.
* **Também usadas como seeds do Systemplane:** `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC`, `PLUGIN_AUTH_*`, `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*`, `COB_*`, `SPI_*`, `KEY_CACHE_TTL_SEC` e `VSYNC_*`.
Defina os seeds no bloco de Systemplane dono do domínio, não no bloco de API ou de worker. As chaves sensíveis continuam marcadas com `🔒` nas tabelas abaixo.
| Bloco do chart | Seeds específicos do domínio |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `spiSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*` e `COB_*`. |
| `dictSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `CRM_*`, `SPI_*`, `KEY_CACHE_TTL_SEC` e `VSYNC_*`. |
| `cobSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET` e `DICT_ROUTING_MODE`. |
Os três blocos também recebem os seeds compartilhados `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC` e `PLUGIN_AUTH_*`.
O Pix Lerian não expõe descoberta de catálogo. Use esta página como referência das chaves aceitas e veja [Systemplane](/pt/reference/platform/systemplane/overview) para o modelo de autorização e de atualização em tempo de execução.
## Servidor e modo de deploy
Cada componente recebe `SERVER_ADDRESS` de `.configmap.SERVER_ADDRESS`. O valor deve corresponder a `.service.port` no mesmo `values.yaml`. As probes de liveness e readiness usam essa porta. Veja [Servidor](/pt/reference/byoc-configuration#server) e [Health e readiness](/pt/reference/health-and-readiness).
| Variável | Padrão / Obrigatório | Descrição |
| --------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `APPLICATION_NAME` | Definido pelo chart | Identidade do componente usada para licenciamento, logs e telemetria. Não sobrescreva o valor fornecido pelo chart. |
| `SERVER_ADDRESS` | Definido pelo chart | Endereço HTTP de escuta no formato `host:port`; ele deve corresponder ao `targetPort` do componente. |
| `DEPLOYMENT_MODE` | `byoc` | Modo de deploy entregue aos clientes. Mantenha o valor definido pelo chart. |
| `REQUEST_TIMEOUT_SEC` | `30` | Timeout padrão das requisições HTTP, em segundos. |
| `PLUGIN_AUTH_ENABLED` | `false` | Exige autenticação do Access Manager nas rotas protegidas. Habilite em produção. |
| `PLUGIN_AUTH_URL` | **Obrigatório com autenticação ou M2M** | URL base do Access Manager usada na autenticação de entrada e nos clientes OAuth entre componentes. |
| `LICENSE_KEY` | 🔒 **Obrigatório em BYOC** | Chave de licença do Pix Lerian. |
| `ORGANIZATION_IDS` | **Obrigatório quando `LICENSE_KEY` está definida** | Escopo da licença: `global` ou uma lista de organizações separada por vírgulas. Use este nome exato; os binários atuais não leem `LICENSE_ORGANIZATION_IDS`. |
| `SWAGGER_ENABLED` | Habilitado fora de produção | Controla a especificação OpenAPI e a interface de exploração servida pelo componente. |
## Persistência e configuração em tempo de execução
SPI, DICT, COB e o adaptador mantêm armazenamentos separados. Não reutilize o mesmo banco de dados lógico entre domínios.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | 🔒 **Obrigatório para componentes com persistência** | DSN do PostgreSQL do componente, usado pelos serviços que persistem dados de negócio e pelos componentes de configuração. |
| `SYSTEMPLANE_POSTGRES_DSN` | 🔒 `DATABASE_URL` em SPI, DICT e COB | DSN dedicado para ler a configuração de tempo de execução. Use o valor renderizado pelo chart do componente. |
| `SYSTEMPLANE_SECRET_MASTER_KEY` | 🔒 **Obrigatório em BYOC** | Chave AES-256-GCM de 32 bytes usada para criptografar os valores secretos no armazenamento de configuração. |
| `VALKEY_URL` | 🔒 — | URL do Valkey/Redis usada para idempotência, deduplicação e cache. Alguns fluxos degradam ou falham com segurança quando ela não tem valor. |
| `KEY_CACHE_TTL_SEC` | `60` | TTL do cache de consulta de chaves do DICT, em segundos. |
Valores de identidade, URLs e credenciais declarados nos componentes de configuração são usados **apenas como seeds de primeira inicialização**. Depois que uma chave existe no armazenamento de tempo de execução, reiniciar o serviço não sobrescreve o valor. Faça as mudanças posteriores pelo plano de configuração autenticado.
## Identidade da instituição
| Variável | Padrão / Obrigatório | Descrição |
| ------------------ | ----------------------------------------- | ----------------------------------------------------------------- |
| `ORGANIZATION_ID` | **Obrigatório para BYOC** | UUID da organização Midaz usada por SPI, DICT e COB. |
| `ISPB` | **Obrigatório para BYOC** | Identificador de oito dígitos da instituição participante. |
| `ADAPTER_BASE_URL` | **Obrigatório para os fluxos conectados** | URL base do adaptador de conectividade usada por SPI, DICT e COB. |
## Midaz e CRM
O SPI usa o Midaz para contabilidade. O SPI e o DICT usam o CRM para validar contas e titulares nos fluxos que exigem essa informação.
| Variável | Padrão / Obrigatório | Descrição |
| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ |
| `MIDAZ_BASE_URL` | **Obrigatório para contabilidade** | URL base compartilhada pelas APIs de onboarding e de transação do Midaz. |
| `MIDAZ_LEDGER_ID` | **Obrigatório para contabilidade** | UUID do ledger que registra as operações de Pix. |
| `MIDAZ_CLIENT_ID` | **Obrigatório com autenticação** | Client ID OAuth usado pelo SPI para chamar o Midaz. |
| `MIDAZ_CLIENT_SECRET` | 🔒 **Obrigatório com autenticação** | Client secret OAuth usado pelo SPI para chamar o Midaz. |
| `CRM_BASE_URL` | **Obrigatório para os fluxos de validação** | URL base do CRM. |
| `CRM_CLIENT_ID` | **Obrigatório com autenticação** | Client ID OAuth usado pelo SPI e pelo DICT para chamar o CRM. |
| `CRM_CLIENT_SECRET` | 🔒 **Obrigatório com autenticação** | Client secret OAuth usado pelo SPI e pelo DICT para chamar o CRM. |
## Integrações entre domínios
As URLs abaixo apontam para componentes do Pix Lerian com o deploy já feito. Elas configuram a comunicação entre SPI, DICT, COB e o adaptador sem mudar o contrato consumido pela aplicação cliente.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `DICT_BASE_URL` | **Obrigatório para os componentes que consultam o DICT** | URL base do domínio DICT. Usada por SPI, COB e o adaptador. |
| `DICT_CLIENT_ID` | **Obrigatório com autenticação** | Client ID OAuth para as chamadas ao DICT. |
| `DICT_CLIENT_SECRET` | 🔒 **Obrigatório com autenticação** | Client secret OAuth para as chamadas ao DICT. |
| `DICT_ROUTING_MODE` | `hub` | Camada de descoberta do DICT: `hub` ou `proxy`. A URL configurada deve apontar para a mesma camada. |
| `COB_BASE_URL` | **Obrigatório para os componentes que consultam o COB** | URL base do domínio COB. Usada pelo SPI e pelo adaptador. |
| `COB_CLIENT_ID` | **Obrigatório com autenticação** | Client ID OAuth para as chamadas ao COB. |
| `COB_CLIENT_SECRET` | 🔒 **Obrigatório com autenticação** | Client secret OAuth para as chamadas ao COB. |
| `COB_ROUTING_MODE` | `hub` | Camada de descoberta do COB: `hub` ou `proxy`. A URL configurada deve apontar para a mesma camada. |
| `SPI_BASE_URL` | **Obrigatório para os componentes que consultam o SPI** | URL base do domínio SPI. Usada pelo DICT e pelo adaptador. |
| `SPI_CLIENT_ID` | **Obrigatório com autenticação** | Client ID OAuth para as chamadas ao SPI. |
| `SPI_CLIENT_SECRET` | 🔒 **Obrigatório com autenticação** | Client secret OAuth para as chamadas ao SPI. |
## Conciliação do DICT (VSync)
O worker VSync concilia o banco de dados persistido do DICT com a fonte regulatória. O transporte RabbitMQ vem habilitado por padrão. Quando ativo, ele exige uma URI válida.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
| `VSYNC_ENABLED` | `true` | Habilita o worker de conciliação. |
| `VSYNC_FILE_RECON_ENABLED` | `true` | Habilita a conciliação por arquivo. |
| `RABBITMQ_ENABLED` | `true` | Habilita o transporte RabbitMQ do VSync. |
| `RABBITMQ_URI` | 🔒 **Obrigatório quando `RABBITMQ_ENABLED=true`** | URI de conexão do RabbitMQ. Use `amqps://` em produção. |
| `VSYNC_CHUNK_CONSUMER_WORKERS` | `3` | Número de consumidores de chunk em paralelo. |
| `VSYNC_JOBS_CONSUMER_WORKERS` | `3` | Número de consumidores de job em paralelo. |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC` | `120` | Intervalo, em segundos, entre as varreduras de jobs travados. |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30` | Tempo, em minutos, antes de um chunk ser considerado travado. |
| `VSYNC_MAX_JOB_ATTEMPTS` | `3` | Número máximo de tentativas de um job de conciliação. |
| `VSYNC_EVENTSYNC_MAX_PAGES` | `100` | Número máximo de páginas processadas por ciclo de sincronização de eventos. |
| `VSYNC_GATE_TTL_SEC` | `3600` | TTL, em segundos, do lock que protege as mutações durante a conciliação. |
## Streaming e observabilidade
A publicação de CloudEvents pelo SPI, DICT e COB usa a família `STREAMING_*` e continua desabilitada por padrão. Quando `STREAMING_ENABLED=true`, `STREAMING_BROKERS` é obrigatório. Se você definir `STREAMING_CLOUDEVENTS_SOURCE`, o único valor aceito é `plugin-br-pix-lerian`. Veja [Streaming e outbox](/pt/reference/byoc-configuration#streaming-and-outbox) e [Observabilidade](/pt/reference/byoc-configuration#observability) para os demais parâmetros de broker, TLS, SASL e OpenTelemetry.
## Fonte de configuração de bootstrap
O `values.yaml` do Helm chart entregue é a fonte de bootstrap do deploy. Mantenha-o alinhado com a versão do chart e preserve os nomes dos blocos de componente e das variáveis. Injete os segredos a partir do cofre de segredos e nunca guarde credenciais em texto puro no repositório. Depois de aplicar os seeds, use o Systemplane para mudar as chaves de tempo de execução.
## Health e readiness
Configure as probes por `.livenessProbe.path` e `.readinessProbe.path` no `values.yaml`. Os caminhos padrão variam por componente. Não suponha caminhos `/health` e `/readyz` sem prefixo.
A probe de liveness verifica se o processo está vivo. A probe de readiness verifica se as dependências e a configuração necessárias permitem que o componente receba tráfego. Não roteie tráfego para um componente até a probe de readiness dele passar.