> ## 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 em tempo de deploy do Lerian SCR: o canal de consulta do BACEN, os datastores, o streaming de eventos, o armazenamento de segredos e as chaves de criptografia em repouso.

O Lerian SCR é o trilho de propriedade da Lerian que consulta posições de tomadores no BACEN. Você define essas variáveis em tempo de deploy. Uma reinicialização do serviço as coloca em vigor. O system plane mantém um segundo conjunto de parâmetros que um operador altera após o deployment. Veja [Operações](https://docs.lerian.studio/pt/rails/scr/scr-operations.md) e [System plane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md).

Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. `—` significa nenhum padrão. Um qualificador em negrito marca um valor que você deve definir. Uma linha marcada com `Sensitive.` carrega material de credencial ou de chave. Injete-o a partir do seu gerenciador de segredos em tempo de deploy, e nunca faça commit de um valor.

A postura estrita cobre um nome de ambiente de produção e o modo de deployment `saas`. **Obrigatório em produção** marca um valor que a postura estrita exige. Um valor ausente ou inseguro ali recusa o boot.

## Serviço e runtime

***

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SERVICE_NAME` | `br-scr` | Identidade do serviço registrada nos logs e na telemetria. |
| `ENV_NAME` | `development` | Ambiente de deployment. Os valores `production` e `prod` selecionam a postura estrita. |
| `LOG_LEVEL` | `info` | Nível mínimo de log. Um de `debug`, `info`, `warn`, `error`. Outro valor recusa o boot. |
| `SERVER_PORT` | `3003` | Porta HTTP de escuta de entrada. |
| `DEPLOYMENT_MODE` | `local`, **Obrigatório em produção** | Postura de TLS. Um de `local`, `byoc`, `saas`. O valor `saas` seleciona a postura estrita, e também exige `ENV_NAME` definido como `production`, `prod` ou `staging`. A postura estrita exige um valor explícito. |
| `TRUSTED_PROXIES` | — | Endereços de proxy ou intervalos CIDR separados por vírgula cujo IP de cliente encaminhado o serviço confia. Vazio não confia em nenhum proxy e lê o peer direto. Uma entrada que não é um endereço IP nem um intervalo CIDR impede o serviço de iniciar. Um intervalo wildcard também recusa um boot estrito. |
| `PROXY_HEADER` | `X-Forwarded-For` | Header do qual o serviço lê o IP do cliente. Aplica-se apenas quando a lista de proxies confiáveis está definida. |
| `CORS_ALLOWED_ORIGINS` | — | Origens de navegador, separadas por vírgula, que o serviço atende, cada uma como `scheme://host[:port]`. Vazio não atende nenhuma chamada de origem cruzada. Um curinga recusa o boot, e a postura estrita aceita apenas origens `https`. |
| `READYZ_DRAIN_DELAY` | `3s` | Janela mantida aberta depois que a prontidão reporta 503 no encerramento, antes que o listener feche. Um `0` desativa a espera. Um valor inválido ou negativo volta ao padrão. O serviço limita a janela a um terço do orçamento de encerramento. |

> [!NOTE]
>
> O Lerian SCR expõe `/health`, `/readyz` e `/version` na porta principal. Veja [Saúde e prontidão](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato do probe, e [Operações](https://docs.lerian.studio/pt/rails/scr/scr-operations.md) para as verificações de prontidão.

## Postgres

***

O Postgres armazena a trilha de auditoria, os metadados de credencial e o outbox. Um operador aplica o esquema antes do primeiro boot. O serviço lê o esquema e nunca o cria. O serviço recusa iniciar quando o Postgres não responde em até 10 segundos.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `POSTGRES_HOST` | **Obrigatório em produção** | Host do banco de dados. |
| `POSTGRES_PORT` | `5432` | Porta do banco de dados. |
| `POSTGRES_USER` | **Obrigatório em produção** | Usuário do banco de dados. |
| `POSTGRES_PASSWORD` | — | Senha para esse usuário. Sensível. |
| `POSTGRES_DB` | **Obrigatório em produção** | Nome do banco de dados. |
| `POSTGRES_SSLMODE` | `disable`, **Obrigatório em produção** | Modo de TLS da conexão. A postura estrita aceita apenas `require`, `verify-ca` ou `verify-full`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Máximo de conexões abertas no pool. Um valor de `0` ou menor restaura o padrão. |
| `POSTGRES_MAX_IDLE_CONNS` | `10` | Máximo de conexões ociosas no pool. Um valor de `0` ou menor restaura o padrão. |
| `POSTGRES_CONN_LIFETIME` | `30m` | Tempo de vida máximo de uma conexão em pool. Um valor não interpretável volta ao padrão. |
| `POSTGRES_CONN_IDLE_TIME` | `5m` | Tempo ocioso máximo de uma conexão em pool. Um valor não interpretável volta ao padrão. |

## Redis

***

O Redis dá suporte ao cache de resultado, à janela de idempotência e ao rate limit de entrada.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `REDIS_HOST` | **Obrigatório** | Host do cache. Todo modo de deployment o exige, a menos que o operador declare o opt-out abaixo. Caso contrário, um host em branco recusa o boot. |
| `REDIS_PORT` | `6379` | Porta do cache. |
| `REDIS_PASSWORD` | — | Senha do cache. Sensível. |
| `REDIS_TLS_ENABLED` | `false`, **Obrigatório em produção** | A postura estrita exige `true` quando o Redis está configurado. |
| `SCR_REDIS_DISABLED` | `false` | O valor `true` é a declaração explícita de que este deployment roda sem Redis. A consulta e a atualização de credencial então respondem `SCR-9002`. |
| `RATE_LIMIT_ENABLED` | `false` | O valor `true` ativa o rate limit de entrada que `scr.rate_limit` configura. |

## Streaming

***

O dispatcher do outbox publica os eventos de consulta. Nenhuma variável define o tópico, porque o serviço o deriva a partir da origem do evento. As cinco primeiras variáveis pertencem ao Lerian SCR. As demais pertencem à biblioteca de streaming, que aplica o TLS do broker e as credenciais SASL à conexão.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SCR_STREAMING_BROKERS` | **Obrigatório** | Endereços de broker separados por vírgula. Todo modo de deployment os exige, a menos que o operador declare o opt-out abaixo. Caso contrário, uma lista em branco recusa o boot. |
| `SCR_STREAMING_CLIENT_ID` | `br-scr` | Identificador de cliente do produtor. |
| `SCR_STREAMING_SOURCE` | `br-scr` | Origem do CloudEvents, e a origem do nome do tópico. O boot recusa qualquer outro valor. O serviço compara o valor bruto, então preenchimento também recusa o boot. |
| `SCR_STREAMING_TLS` | `false`, **Obrigatório em produção** | A postura estrita exige `true` quando brokers estão configurados. Um `true` aqui também exige `STREAMING_TLS_ENABLED=true`. |
| `SCR_STREAMING_EMISSION_DISABLED` | `false` | O valor `true` interrompe o dispatcher. Os eventos permanecem como linhas pendentes no outbox, e são enviados depois que a emissão volta a ser ativada e o serviço reinicia. |
| `STREAMING_TLS_ENABLED` | `false` | Habilita a conexão TLS com o broker. |
| `STREAMING_TLS_CA_CERT` | — | Autoridade certificadora PEM codificada em base64. Um broker atrás de uma autoridade privada precisa dela. Sem ela, apenas um certificado de broker publicamente confiável se valida. |
| `STREAMING_SASL_MECHANISM` | — | Mecanismo SASL para o produtor. Sem um mecanismo, o produtor se conecta de forma anônima e não apresenta nenhum principal para a concessão de escrita. |
| `STREAMING_SASL_USERNAME` | — | Usuário SASL. |
| `STREAMING_SASL_PASSWORD` | — | Senha SASL. Sensível. |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | O valor `true` coloca as credenciais SASL na rede em texto claro. Mantenha-o `false`. |

## Autenticação

***

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `—`, **Obrigatório** | `true` envia cada requisição protegida por gate ao Lerian Access Manager. `false` pula apenas essa chamada; um bearer token continua obrigatório. Apenas um `ENV_NAME` de desenvolvimento fora de `saas` aceita `false`. Qualquer valor diferente de `true` ou `false` impede o serviço de iniciar. |
| `PLUGIN_AUTH_ADDRESS` | **Obrigatório em produção** | URL base do servidor de autorização. A postura estrita exige um esquema `https`. |

## Declaração de permissões

***

O Lerian SCR pode publicar seu próprio conjunto de permissões no Access Manager na inicialização. `IDP_DECLARATION_ENABLED=true` ativa isso, e qualquer valor diferente de `true` ou `false` impede o serviço de iniciar. Com a declaração ativa, uma variável ausente abaixo recusa iniciar.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `IDP_DECLARATION_ENABLED` | `false` | Publica o conjunto de permissões na inicialização. |
| `IDP_HOST` | **Obrigatório com a declaração** | URL base do Access Manager para a qual o conjunto é publicado. |
| `IDP_M2M_CLIENT_ID` | **Obrigatório com a declaração** | Client ID da aplicação machine-to-machine do serviço, cujo nome deve ser `scr`. |
| `IDP_M2M_CLIENT_SECRET` | **Obrigatório com a declaração** | Client secret dessa aplicação. Sensível. |

Com a declaração ativa, `PLUGIN_AUTH_ENABLED` deve ser `true` e `PLUGIN_AUTH_ADDRESS` deve estar definido, porque o serviço os usa para obter o token que a publicação usa.

## Canal do BACEN

***

O canal de saída alcança o web service de consulta do BACEN por HTTPS com credenciais HTTP Basic. O serviço lê as duas variáveis de credencial apenas quando o tipo de armazenamento de segredos é o ambiente.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SCR_WSSCR2N_BASE_URL` | **Obrigatório em produção** | URL base completa, incluindo o context path do BACEN. O adapter anexa apenas o caminho da operação. O host de homologação é `www9.bcb.gov.br` e o host de produção é `scr.bcb.gov.br`. A postura estrita exige um esquema `https`. |
| `SCR_WSSCR2N_BASIC_USER` | **Obrigatório em produção com o armazenamento de segredos de ambiente** | O usuário de serviço virtual da instituição, no formato `UUUUUDDDD.OPERADOR` do BACEN. Não é o nome da transação do Sisbacen. |
| `SCR_WSSCR2N_BASIC_PASSWORD` | **Obrigatório em produção com o armazenamento de segredos de ambiente** | Senha para esse usuário de serviço. Sensível. |

## Armazenamento de segredos

***

O armazenamento de segredos resolve a credencial do canal do BACEN.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SECRET_STORE_KIND` | `env` | Fonte da credencial. O valor `env` lê a credencial a partir do ambiente. O valor `aws` a lê a partir do vault gerenciado, e monta as operações de credencial. Outro valor recusa o boot. |
| `AWS_REGION` | **Obrigatório em produção com o vault gerenciado** | Região a partir da qual o cliente do vault gerenciado resolve seu endpoint. |
| `SECRET_STORE_PREFIX` | `scr` | Prefixo de path do vault. A credencial fica em `<prefix>/wsscr2n`. Não é um segredo. |

## Criptografia em repouso

***

A trilha de auditoria criptografa os dados do tomador e os indexa de forma cega. Duas chaves independentes fazem esse trabalho. Uma única chave para as duas vazaria a relação entre o texto cifrado e o índice. Fora da postura estrita, o serviço volta a chaves de desenvolvimento bem conhecidas, que nunca devem alcançar um runtime regulado.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SCR_ATREST_ENCRYPTION_KEY` | **Obrigatório em produção** | Chave de envelope AES-256, como base64 ou como 32 bytes brutos. Sensível. |
| `SCR_ATREST_BLIND_INDEX_KEY` | **Obrigatório em produção** | Chave HMAC para o índice pesquisável de documento. Deve conter pelo menos 32 caracteres, e deve ser diferente da chave de envelope. Sensível. |

## Licença

***

O Lerian SCR recusa iniciar sem uma licença da Lerian, em todos os ambientes. Nenhum ajuste desliga a verificação.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_KEY` | **Obrigatório** | Chave de licença da Lerian. Sensível. |
| `LICENSE_FILE_PATH` | — | Caminho de um arquivo de licença. Quando ela está definida, o serviço usa o arquivo e ignora `LICENSE_KEY`, e um arquivo que o serviço recusa impede a inicialização. Deixe-a vazia e defina `LICENSE_KEY`. |

## Telemetria e métricas

***

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `ENABLE_TELEMETRY` | `false` | O valor `true` conecta os provedores OpenTelemetry. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | Endpoint do collector. Com a telemetria ativada, a postura estrita exige um esquema `https`. |
| `METRICS_PROMETHEUS_ENABLED` | `false` | O valor `true` ativa um listener de scrape dedicado do Prometheus. |
| `METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9075` | Endereço de bind desse listener. A porta da aplicação não carrega nenhuma rota `/metrics`. |


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