> ## 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 de deploy do Lerian STA: o ambiente-alvo do BACEN, armazenamento de objetos compatível com S3 e chaves mestras de criptografia envelope.

O Lerian STA é o trilho de propriedade da Lerian que transmite e recebe arquivos com o hub STA do BACEN. Você define essas variáveis no momento do deploy. Um restart do serviço as torna efetivas. Todo serviço Go da Lerian compartilha uma base universal: servidor, armazenamentos de dados, telemetria e autenticação de plugin. A [referência de configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) documenta essa base uma única vez. Esta página cobre as variáveis específicas do Lerian STA.

Para instalar ou atualizar o Lerian STA, consulte o [README do chart do Lerian STA](https://github.com/LerianStudio/helm/tree/main/charts/br-sta).

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, como **Obrigatório** ou **Obrigatório em produção**. `—` significa que não há padrão. Uma variável marcada como **Sensível** carrega credencial ou material de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor. Um valor que não pode ser lido como o tipo da sua variável interrompe o boot. Uma variável booleana aceita apenas `true` ou `false`.

## Serviço e runtime

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SERVER_ADDRESS` | `:4028` | Endereço HTTP principal de escuta. As sondas de liveness, readiness, metrics e version se ligam a essa mesma porta. |
| `DEPLOYMENT_MODE` | `local` | Modelo de deploy: `local`, `byoc` ou `saas`, em maiúsculas ou minúsculas. Outro valor interrompe o boot. Com `saas`, o boot falha quando uma conexão configurada com PostgreSQL, Redis, RabbitMQ, armazenamento de objetos ou os brokers de streaming não exige TLS. |
| `PLUGIN_AUTH_ENABLED` | **Obrigatório** | `true` ou `false`. Um valor vazio ou outro valor interrompe o boot. `true` ativa a autorização pelo Lerian Access Manager. O Lerian STA aceita `false` apenas quando `ENV_NAME` é `development`, `develop`, `dev`, `local` ou `test`, e `DEPLOYMENT_MODE` não é `saas`. Com `false`, cada requisição protegida ainda precisa de um bearer token que nomeia um principal, e o Lerian STA pula apenas a chamada ao Access Manager. |
| `PLUGIN_AUTH_HOST` | **Obrigatório** quando `PLUGIN_AUTH_ENABLED` é `true` | Endereço do Lerian Access Manager. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a API administrativa de configuração em runtime do [Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) sob o prefixo `/system` na porta principal. Desativada por padrão (modo apenas variável de ambiente). |
| `BACEN_ENVIRONMENT` | `homologation` | Seleciona o ambiente do STA do BACEN que toda chamada ao BACEN usa como alvo: `homologation` (homologação) ou `production` (produção). Um valor não reconhecido cai para `homologation`, para que uma stack fora de produção não consiga rotear tráfego para o serviço BACEN em produção. |
| `SCHEDULER_ENABLED` | `false` | Roda os jobs agendados do worker, incluindo os pollers de status de saída, a varredura de credenciais para rotações travadas e a exclusão de transferências canceladas e inconsistentes depois de 7 dias. |

> [!NOTE]
>
> O Lerian STA expõe `/health` (liveness) e `/readyz` (readiness) na porta principal, além de `/version` e `/metrics`. Veja [Health e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato da sonda.

## Licença

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_FILE_PATH` | **Obrigatório** sem `LICENSE_KEY` | Caminho do arquivo de licença assinado que a Lerian emite. O Lerian STA verifica o arquivo localmente e não chama o [serviço de licenças](https://docs.lerian.studio/pt/platform/licensing/license-manager.md). Se o arquivo não licencia o Lerian STA, o boot falha. O Lerian STA não tenta usar `LICENSE_KEY` no lugar dele. O Lerian STA lê o arquivo de novo aproximadamente a cada hora, então um arquivo renovado entra em vigor sem restart. O arquivo contém a chave de licença, então guarde-o em um secret. No Kubernetes, monte esse Secret como um diretório, sem `subPath`, porque o Kubernetes não atualiza uma montagem `subPath`. |
| `LICENSE_KEY` | **Obrigatório** sem `LICENSE_FILE_PATH` | Chave de licença emitida pela Lerian. O Lerian STA a ignora quando `LICENSE_FILE_PATH` está definida. Sensível. |
| `ORGANIZATION_IDS` | **Obrigatório** | Escopo de organização que a licença cobre. |

## Transferências

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `TRANSFER_SCHEDULER_ENABLED` | `false` | Roda o loop do worker que envia as transferências de saída ao BACEN. Enquanto for `false`, o Lerian STA aceita e armazena novas transferências de saída, mas não envia nenhuma delas. |
| `TRANSFER_INBOUND_ENABLED` | `false` | Habilita o pipeline de transferência de entrada (baixado do BACEN). Não muda a exigência do bucket em produção, porque as transferências de saída também usam o bucket. |
| `TRANSFER_MAX_ATTEMPTS` | `5` | Tentativas que uma transferência de saída recebe antes que o Lerian STA a cancele, de 1 a 10. Chave de runtime: `sta.upload.max_attempts`. |
| `TRANSFER_TTL_HOURS` | `44` | Tempo de vida em tempo real de uma transferência de saída depois que o BACEN atribui seu protocolo, de 1 a 44 horas. Chave de runtime: `sta.upload.ttl_hours`. |
| `TRANSFER_MAX_FILE_SIZE_BYTES` | `5368709120` | Tamanho máximo do arquivo que uma nova transferência de saída referencia, em bytes (5 GiB). |

## Armazenamento de objetos

O Lerian STA persiste os bytes de transferência e os downloads de entrada em um armazenamento de objetos compatível com S3.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Obrigatório em produção** | Bucket que guarda as duas direções de transferência. O boot em produção é recusado se estiver vazio, independentemente de as transferências de entrada estarem habilitadas. |
| `TRANSFER_S3_REGION` | `us-east-1` | Região do bucket de transferências. |
| `TRANSFER_S3_ENDPOINT` | — | Endpoint de um armazenamento compatível com S3, como o MinIO. Deixe sem definir para o AWS S3. |
| `TRANSFER_S3_PATH_STYLE` | `false` | Usa endereçamento path-style, que a maioria dos armazenamentos compatíveis com S3 exige. |
| `TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES` | `5368709120` | Tamanho máximo de arquivo de entrada anunciado pelo BACEN, em bytes (5 GiB). Um valor `0` ou menor desabilita esse limite de admissão. |
| `TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO` | `100` | Proporção máxima entre o tamanho da entrada extraída e seu envelope ZIP entregue. Um valor `0` ou menor desabilita a verificação de proporção. |
| `TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES` | `5368709120` | Tamanho máximo absoluto da única entrada ZIP extraída, em bytes (5 GiB). Um valor `0` ou menor desabilita esse limite. |
| `AWS_REGION` | — | Região do AWS KMS quando `MASTER_KEY_KMS_REGION` está vazio. Não configura o armazenamento de objetos. |
| `AWS_ACCESS_KEY_ID` | — | Chave de acesso para o armazenamento de objetos. Sensível. Deixe sem definir quando uma role IAM anexada fornece as credenciais. |
| `AWS_SECRET_ACCESS_KEY` | — | Chave secreta para o armazenamento de objetos. Sensível. Deixe sem definir quando uma role IAM anexada fornece as credenciais. |

## Criptografia envelope

O Lerian STA protege as credenciais de operador com criptografia envelope AES-GCM. Todo processo do Lerian STA precisa do material de chave mestra. Um valor ausente ou malformado aborta o boot.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `MASTER_KEY_PROVIDER` | `envvar` | Origem da chave de criptografia envelope: `envvar` (chave lida de `MASTER_KEYS`) ou `aws-kms` (chave envolvida por um KMS de nuvem). |
| `MASTER_KEY_VERSION` | **Obrigatório** | Seleciona a versão de chave mestra atualmente ativa. Deve corresponder a uma versão presente em `MASTER_KEYS`. |
| `MASTER_KEYS` | **Obrigatório** | Pares `version:key` separados por vírgula. Sensível. Com `envvar`, cada valor é uma chave AES-256 de 64 caracteres hex: `version:<64-hex-key>`. Com `aws-kms`, cada valor é um ciphertext KMS em base64: `version:<base64-ciphertext>`, decifrado no processo. Obtenha-a a partir do seu gerenciador de segredos. Um valor ausente ou malformado aborta o boot. |
| `MASTER_KEY_KMS_KEY_ID` | **Obrigatório se `aws-kms`** | Identificador da chave AWS KMS usada para decifrar o ciphertext de `MASTER_KEYS`. Com `aws-kms`, o ciphertext é decifrado no processo do STA. |
| `MASTER_KEY_KMS_REGION` | — | Região da chave AWS KMS. Quando vazia, o Lerian STA usa `AWS_REGION`. |
| `CREDENTIALS_RECOVERY_ON_BOOT` | `false` | Defina explicitamente como `true` para rodar, uma vez no boot, a varredura de recuperação de credenciais do lado do worker para credenciais deixadas em rotação por um processo anterior. |

> [!NOTE]
>
> O Lerian STA roda seu pipeline de auditoria em um worker dedicado. O export generator também precisa do seu bucket S3.
>
> Configure as flags de habilitação e os parâmetros obrigatórios pelas famílias `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_VERIFIER_*`, `AUDIT_EXPORT_GENERATOR_*` e `AUDIT_EXPORT_RATE_LIMIT_*`. O runtime aplica os padrões declarados delas. O partition manager e o verifier rodam por padrão. Habilite cada um dos outros jobs antes de esperar que ele rode.

## Streaming

O Lerian STA e a biblioteca de streaming da Lerian leem a família `STREAMING_`. O [Lerian Streaming Hub](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md) entrega os eventos publicados.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Chave mestra para a emissão de eventos de negócio para os brokers de streaming. Ela também exige `BUSINESS_EVENTS_ENABLED` e `RABBITMQ_ENABLED`, ambas `true` por padrão. Enquanto ela está desativada, o serviço não envia nenhum evento aos brokers. |
| `STREAMING_BROKERS` | **Obrigatório** quando o streaming está ativado | Lista de bootstrap de brokers separada por vírgulas. Uma configuração ativada com uma lista vazia recusa o boot. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `br-sta` (fixo) | A fonte CloudEvents deste serviço. Ela define o namespace do tópico e o prefixo do tipo de evento. Deixe-a sem definir. Qualquer valor não vazio diferente de `br-sta` recusa o boot, mesmo quando o streaming está desativado. |
| `STREAMING_CLIENT_ID` | `br-sta` | Identificador de cliente do broker usado para diagnósticos do lado do broker. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Proporção de falhas que abre o circuit breaker do produtor. Com o streaming ativado, um valor igual ou menor que 0, ou maior que 1, recusa o boot. |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Mínimo de requisições antes que o circuit breaker do produtor avalie a proporção de falhas. Com o streaming ativado, um valor negativo recusa o boot. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Tempo de resfriamento no estado aberto, em segundos, para o circuit breaker do produtor. Com o streaming ativado, um valor negativo recusa o boot. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Janela máxima de drenagem e flush, em segundos, quando o produtor encerra. Com o streaming ativado, um valor de 0 ou menos recusa o boot. |
| `STREAMING_TOPIC_AUTO_PROVISION` | `true` | Com o streaming ativado, o serviço cria o seu tópico de eventos `lerian.streaming.br-sta` e o seu tópico de dead-letter `lerian.streaming.br-sta.dlq` nos brokers durante a inicialização, quando eles não existem. Uma criação com falha registra um aviso e o boot continua. Defina-a como `false` quando você cria os tópicos com antecedência. |
| `STREAMING_TOPIC_PARTITIONS` | `-1` | Número de partições de um tópico que o serviço cria. Um valor menor que 1 usa o padrão do broker. |
| `STREAMING_TOPIC_REPLICATION_FACTOR` | `-1` | Fator de replicação de um tópico que o serviço cria. Um valor menor que 1 usa o padrão do broker. |
| `STREAMING_TLS_ENABLED` | `false` (**Obrigatório** como `true` com `DEPLOYMENT_MODE=saas` quando o streaming está ativado) | Ativa o TLS na conexão com o broker. A versão mínima é TLS 1.2. |
| `STREAMING_TLS_CA_CERT` | — | Autoridade certificadora PEM para um broker privado ou on-premises, em PEM puro ou codificado em base64. Ela vale quando `STREAMING_TLS_ENABLED` é `true`. Um valor vazio usa o trust store do host. |
| `STREAMING_SASL_MECHANISM` | — (**Obrigatório** com `DEPLOYMENT_MODE=saas` quando o streaming está ativado) | Mecanismo de autenticação do broker: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Um valor vazio desativa a autenticação do broker. Com o streaming ativado, um mecanismo sem as credenciais dele, ou sem `STREAMING_TLS_ENABLED=true`, recusa o boot. |
| `STREAMING_SASL_USERNAME` | — (**Obrigatório** com `DEPLOYMENT_MODE=saas` quando o streaming está ativado) | Nome de usuário de autenticação do broker. |
| `STREAMING_SASL_PASSWORD` | — (**Obrigatório** com `DEPLOYMENT_MODE=saas` quando o streaming está ativado) | Senha de autenticação do broker. Sensível. |

## Envios do Reporter

Estas variáveis controlam o consumidor que envia ao BACEN os relatórios regulatórios aprovados no Reporter. Veja [Envios regulatórios do Reporter](https://docs.lerian.studio/pt/rails/sta/sta-integration.md#regulatory-filings-from-reporter).

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `REPORTER_EVENTS_CONSUMER_ENABLED` | `false` | Consome as aprovações de envio regulatório do Reporter e envia os relatórios aprovados ao BACEN. |
| `REPORTER_EVENTS_CONSUMER_EXCHANGE` | **Obrigatório se o consumidor estiver habilitado** | Exchange de eventos do Reporter à qual o consumidor se vincula. |
| `REPORTER_EVENTS_DOCTYPE_RESOLVER` | **Obrigatório se o consumidor estiver habilitado** | Como o Lerian STA obtém o tipo de documento do BACEN de um relatório. Defina `payload` para lê-lo do evento. |


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