> ## 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, multi-tenancy, telemetria, autenticação de plugin e licenciamento. A [referência de configuração BYOC](/pt/reference/byoc-configuration) documenta essa base uma única vez. Esta página cobre apenas as variáveis específicas do Lerian 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.
## 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. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a API administrativa de configuração em runtime do [Systemplane](/pt/reference/platform/systemplane/overview) sob o prefixo `/system` na porta principal. Desativada por padrão (modo apenas variável de ambiente). |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | UUID de fallback usado apenas para o `ce-tenantid` de streaming/outbox quando um evento não tem ID de tenant; não é injetado no contexto comum de requisição ou transferência single-tenant. |
| `BACEN_ENVIRONMENT` | `homologation` | Seleciona o alvo upstream do STA do BACEN para a sonda de conectividade: `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. |
O Lerian STA expõe `/health` (liveness) e `/readyz` (readiness) na porta principal, além de `/version` e `/metrics`. Quando você habilita multi-tenancy, ele também expõe `GET /readyz/tenant/{id}`. Veja [Health e readiness](/pt/reference/health-and-readiness) para o contrato da sonda.
## 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. Cada subsistema configura sua própria conexão pelo AWS SDK, então a mesma configuração atende ao AWS S3, ao MinIO ou a um armazenamento local.
| 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, indexado por prefixo de direção. O boot em produção é recusado se estiver vazio, independentemente de as transferências de entrada estarem habilitadas. |
| `TRANSFER_INBOUND_ENABLED` | `false` | Habilita o pipeline de transferência de entrada (puxado pelo 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_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 para o AWS Secrets Manager M2M e, quando `MASTER_KEY_KMS_REGION` está vazio, o fallback do AWS KMS. 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. O processo gerenciador sempre 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:`, 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. |
| `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. |
O Lerian STA roda seu pipeline de auditoria em um worker dedicado. O publisher, o consumer e o export generator aceitam os modos single-tenant e multi-tenant. O export generator também precisa do seu bucket S3. O partition manager, o cleanup e o verifier exigem multi-tenancy.
Configure as flags de habilitação e os parâmetros obrigatórios pelas famílias `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_CLEANUP_*`, `AUDIT_VERIFIER_*`, `AUDIT_EXPORT_GENERATOR_*` e `AUDIT_EXPORT_RATE_LIMIT_*`. O runtime aplica os padrões declarados delas. Habilite um worker explicitamente antes de esperar que ele rode.