> ## 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 definidas no deploy do Lerian SPB — runtime, conectividade STR/RSFN, assinatura de mensagens e certificados, persistência, eventos e segurança.
O Lerian SPB é a integração de mensageria nativa da Lerian para o STR (Sistema de Transferência de Reservas), alcançando o sistema de liquidação bruta em tempo real do BACEN sobre a RSFN. As variáveis abaixo são definidas no momento do deploy e exigem uma reinicialização do serviço para entrar em vigor. A maioria delas é específica deste rail; para os parâmetros que se comportam da mesma forma em todos os serviços Go da Lerian — postura de deployment, datastores, multi-tenancy, telemetria — consulte a [referência de configuração BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, **Obrigatória** marca uma variável que deve ser definida (globalmente, ou sob a condição indicada). Um qualificador como *Em produção* ou *Se habilitado* restringe quando a exigência se aplica. `—` significa que não há padrão.
O Lerian SPB arma seus controles de segurança mais estritos a partir de `ENV_NAME`: quando definido como `production` ou `staging`, o TLS torna-se obrigatório no Redis, no RabbitMQ e na conexão STR, a assinatura de mensagens deve usar um backend de custódia baseado em hardware, e superfícies exclusivas de desenvolvimento são rejeitadas. `ENV_NAME` não tem padrão — defina-o explicitamente; o serviço se recusa a iniciar quando não está definido ou tem um valor não reconhecido.
## Runtime e servidor
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------- |
| `ENV_NAME` | Ambiente de runtime. Deve ser um de `production`, `staging` ou `develop`. Production e staging armam os controles de segurança descritos acima. | — | Sim |
| `SERVICE_NAME` | Identificador de serviço usado em logs e telemetria. | Padrão do serviço | Não |
| `LOG_LEVEL` | Verbosidade dos logs (`debug`, `info`, `warn`, `error`). | `info` | Não |
| `SERVER_PORT` | Porta de escuta HTTP. As superfícies de liveness, readiness e systemplane se vinculam a essa mesma porta. | `3000` | Não |
| `CORS_ALLOWED_ORIGINS` | Origens CORS permitidas, separadas por vírgula. Em produção/staging, apenas origens `https://` são aceitas e origens localhost são rejeitadas. | `http://localhost:3000` | Não |
| `TRUSTED_PROXIES` | IPs/CIDRs de proxy, separados por vírgula, confiáveis para definir o IP real do cliente. | — | Não |
## Autenticação
O Lerian SPB delega a autorização — incluindo a API de administração do systemplane — ao Access Manager. Consulte a [referência de configuração BYOC](/pt/reference/byoc-configuration#autenticação-de-plugins).
| Variável | Descrição | Padrão | Obrigatória |
| --------------------- | ---------------------------------------------------------- | ----------------------- | ------------- |
| `PLUGIN_AUTH_ENABLED` | Exige autenticação via Access Manager em rotas protegidas. | `true` | Não |
| `PLUGIN_AUTH_ADDRESS` | Endereço do serviço Access Manager. | `http://localhost:4000` | Se habilitado |
## PostgreSQL
| Variável | Descrição | Padrão | Obrigatória |
| ----------------------------- | ----------------------------------------------------------------------------------- | ----------- | ------------------- |
| `POSTGRES_HOST` | Host primário do PostgreSQL. | `localhost` | Sim |
| `POSTGRES_PORT` | Porta primária do PostgreSQL. | `5432` | Não |
| `POSTGRES_USER` | Usuário do banco de dados. | — | Sim |
| `POSTGRES_PASSWORD` | Senha do banco de dados. Sensível — injete no momento do deploy; nunca faça commit. | — | Em produção/staging |
| `POSTGRES_DB` | Nome do banco de dados. | — | Sim |
| `POSTGRES_SSLMODE` | Modo TLS do libpq. Use `require` ou mais forte em produção. | `require` | Não |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexões abertas. | `25` | Não |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexões ociosas. | `10` | Não |
| `POSTGRES_CONN_MAX_LIFETIME` | Tempo máximo de vida da conexão (duração Go, ex: `5m`). | `5m` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME` | Tempo máximo ocioso da conexão (duração Go). | `2m` | Não |
### Réplica PostgreSQL
Réplica de leitura opcional. Todos os campos usam o primário como fallback quando não definidos.
| Variável | Descrição | Padrão | Obrigatória |
| --------------------------- | -------------------------------------------- | ------ | ----------- |
| `POSTGRES_REPLICA_HOST` | Host da réplica. Não definido = sem réplica. | — | Não |
| `POSTGRES_REPLICA_PORT` | Porta da réplica. | — | Não |
| `POSTGRES_REPLICA_USER` | Usuário da réplica. | — | Não |
| `POSTGRES_REPLICA_PASSWORD` | Senha da réplica. Sensível. | — | Não |
| `POSTGRES_REPLICA_DB` | Nome do banco da réplica. | — | Não |
| `POSTGRES_REPLICA_SSLMODE` | Modo TLS da réplica. | — | Não |
## Redis
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------- |
| `REDIS_HOST` | Host do Redis. Deve ser explícito e não-local em produção/staging. | `localhost` | Em produção/staging |
| `REDIS_PORT` | Porta do Redis. | `6379` | Não |
| `REDIS_PASSWORD` | Senha do Redis. Sensível. | — | Em produção/staging |
| `REDIS_DB` | Número do banco de dados Redis. | `0` | Não |
| `REDIS_TLS_ENABLED` | Habilita TLS para o Redis. Deve ser `true` em produção/staging. | `false` | Em produção/staging |
| `REDIS_TLS_CA_CERT_BASE64` | Certificado CA codificado em base64 para o TLS do Redis. Obrigatório quando `REDIS_TLS_ENABLED=true` em produção/staging. | — | Se TLS habilitado |
| `REDIS_POOL_SIZE` | Tamanho do pool de conexões. | `20` | Não |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexões ociosas. | `5` | Não |
## Conectividade STR (RSFN)
O Lerian SPB troca mensagens STR com o BACEN sobre a RSFN usando um transporte IBM MQ. Essas variáveis definem a identidade do participante, a conexão com o queue manager e as filas.
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------- |
| `STR_ISPB` | O ISPB de 8 dígitos do participante. Em produção/staging deve ser um ISPB real explícito, não `00000000`. | `00000000` | Em produção/staging |
| `STR_MQ_HOST` | Host do queue manager. | — | Sim (STR real) |
| `STR_MQ_PORT` | Porta do listener do queue manager. | `1414` | Não |
| `STR_MQ_CHANNEL` | Canal de server-connection do MQ. | `DEV.APP.SVRCONN` | Não |
| `STR_MQ_QUEUE_MGR` | Nome do queue manager. | `QM1` | Não |
| `STR_MQ_USER` | Usuário da conexão MQ. | — | Não |
| `STR_MQ_PASSWORD` | Senha da conexão MQ. Sensível. | — | Não |
| `STR_MQ_TLS_ENABLED` | Habilita TLS mútuo no canal MQ. Obrigatório para uma conexão STR real. | `false` | Em produção/staging |
| `MQSSLKEYR` | Caminho para o repositório de chaves GSKit que dá suporte ao TLS do MQ. A chave privada fica aqui, nunca em uma variável de ambiente. | — | Se TLS habilitado |
| `STR_MQ_SEND_QUEUE` | Fila de requisição de saída. Derivada de `STR_ISPB` quando não definida. | Derivado | Não |
| `STR_MQ_RESPONSE_QUEUE` | Fila de resposta. Derivada de `STR_ISPB` quando não definida. | Derivado | Não |
| `STR_MQ_RECEIVE_QUEUE` | Fila de recebimento de entrada. Derivada de `STR_ISPB` quando não definida. | Derivado | Não |
| `MQ_HEARTBEAT_INTERVAL` | Intervalo de heartbeat do MQ (duração Go). | `300s` | Não |
| `MQ_DISCONNECT_INTERVAL` | Intervalo de desconexão do MQ (duração Go). | `6000s` | Não |
| `MQ_SEQ_WRAP` | Teto de wrap da sequência de mensagens para o canal MQ. | `99999999` | Não |
| `MQ_ADOPTNEWMCA` | Configuração de canal `AdoptNewMCA` do MQ. | `ALL` | Não |
### Circuit breaker
Protege o transporte STR contra um queue manager com falhas.
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------- | ---------------------------------------------------------------------- | ------ | ----------- |
| `CB_MAX_REQUESTS` | Requisições permitidas enquanto o breaker está half-open. | `3` | Não |
| `CB_INTERVAL` | Janela deslizante sobre a qual as falhas são contadas (duração Go). | `30s` | Não |
| `CB_TIMEOUT` | Timeout de recuperação do estado open (duração Go). | `10s` | Não |
| `CB_CONSECUTIVE_FAILURES` | Falhas consecutivas antes de o breaker disparar. | `5` | Não |
| `CB_FAILURE_RATIO` | Razão de falhas que dispara o breaker (0–1). | `0.5` | Não |
| `CB_MIN_REQUESTS` | Mínimo de requisições em uma janela antes de o breaker poder disparar. | `10` | Não |
## Assinatura de mensagens e certificados
As mensagens STR são assinadas digitalmente. Escolha um backend de custódia com `SPB_SIGNER_KIND`; produção e staging rejeitam o backend de arquivo e exigem uma chave baseada em hardware (`pkcs11` ou `kmip`).
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------- |
| `SPB_SIGNER_KIND` | Backend de custódia de assinatura: `file`, `pkcs11` ou `kmip`. `file` é apenas para dev/homologação — rejeitado em produção/staging. (`hsm` e `kms` são declarados mas não implementados.) | `file` | Não |
| `CERT_BASE_PATH` | Diretório base para o material de certificados. | `/certs` | Não |
| `CERT_PATH` | Caminho para o certificado de assinatura. | — | Não |
| `KEY_PATH` | Caminho para a chave privada de assinatura (apenas backend de arquivo). | — | Se `file` |
| `PROCESS_CERT_PATH` | Caminho para o certificado de processo/TLS. | — | Não |
| `PROCESS_PRIVATE_KEY_PATH` | Caminho para a chave privada de processo/TLS. Sensível. | — | Não |
| `BACEN_PUBLIC_CERT_PATH` | Caminho para o certificado público do BACEN, usado para verificar assinaturas de entrada. | — | Não |
| `CERT_READINESS_MIN_DAYS` | Mínimo de dias até o vencimento antes de a verificação de readiness do certificado reportar estado degradado. | `30` | Não |
### Custódia PKCS#11
Obrigatória quando `SPB_SIGNER_KIND=pkcs11`.
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------ | ------------------------------------------------------------ | ------ | ----------- |
| `SPB_PKCS11_MODULE_PATH` | Caminho para a biblioteca do módulo PKCS#11. | — | Se `pkcs11` |
| `SPB_PKCS11_TOKEN_LABEL` | Label do token PKCS#11. | — | Se `pkcs11` |
| `SPB_PKCS11_PIN_FILE` | Caminho para um arquivo que contém o PIN do token. Sensível. | — | Se `pkcs11` |
| `SPB_PKCS11_KEY_LABEL` | Label da chave de assinatura no token. | — | Se `pkcs11` |
### Custódia KMIP
Obrigatória quando `SPB_SIGNER_KIND=kmip` (KMIP-over-HTTP para um HSM de rede).
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------- | ----------------------------------------------------------------------- | ------- | ----------- |
| `SPB_KMIP_BASE_URL` | URL base do serviço KMIP. | — | Se `kmip` |
| `SPB_KMIP_VHSM` | Identificador do HSM virtual. | — | Se `kmip` |
| `SPB_KMIP_CRYPTO_USER` | Usuário cripto do KMIP. | — | Se `kmip` |
| `SPB_KMIP_CRYPTO_USER_TOKEN` | Token do usuário cripto do KMIP. Sensível. | — | Se `kmip` |
| `SPB_KMIP_SIGN_PRIVATE_KEY_UID` | UID da chave privada de assinatura. | — | Se `kmip` |
| `SPB_KMIP_SIGN_PUBLIC_KEY_UID` | UID da chave pública de assinatura. | — | Se `kmip` |
| `SPB_KMIP_DECRYPT_KEY_UID` | UID da chave de descriptografia. | — | Se `kmip` |
| `SPB_KMIP_DIGEST_INFO_PREFIX` | Prefixa o prefixo ASN.1 DigestInfo antes da chamada de assinatura KMIP. | `false` | Não |
## Eventos, outbox e RabbitMQ
O Lerian SPB registra cada mensagem antes do dispatch e publica eventos de ciclo de vida através de um outbox transacional no RabbitMQ.
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------ | ------------------- |
| `EMISSION_REQUIRED` | Quando `true`, o bootstrap falha fechado a menos que a emissão de eventos esteja totalmente conectada. | `false` | Não |
| `RABBITMQ_HOST` | Host do RabbitMQ. | — | Sim (eventos) |
| `RABBITMQ_PORT` | Porta do RabbitMQ. | `5672` | Não |
| `RABBITMQ_USER` | Usuário do RabbitMQ. Não deve ser o padrão `guest` em produção/staging. | `guest` | Em produção/staging |
| `RABBITMQ_PASSWORD` | Senha do RabbitMQ. Sensível. Não deve ser vazia ou o padrão em produção/staging. | `guest` | Em produção/staging |
| `RABBITMQ_VHOST` | Virtual host do RabbitMQ. | `/` | Não |
| `RABBITMQ_STR_EXCHANGE` | Nome do exchange para eventos de ciclo de vida do STR. | `str.events` | Não |
| `RABBITMQ_TLS_ENABLED` | Habilita TLS para o RabbitMQ. Deve ser `true` em produção/staging quando um host está definido. | `false` | Em produção/staging |
| `OUTBOX_DISPATCH_INTERVAL` | Intervalo entre ciclos de dispatch do outbox (duração Go). | `2s` | Não |
| `OUTBOX_BATCH_SIZE` | Linhas drenadas por ciclo de dispatch. | `50` | Não |
| `OUTBOX_MAX_PUBLISH_ATTEMPTS` | Tentativas de publicação antes de um evento ser estacionado. | `3` | Não |
| `OUTBOX_POSTGRES_MAX_OPEN_CONNS` | Máximo de conexões abertas para o pool do outbox. | `10` | Não |
| `OUTBOX_POSTGRES_MAX_IDLE_CONNS` | Máximo de conexões ociosas para o pool do outbox. | `5` | Não |
| `EVENT_DELIVERY_BATCH_SIZE` | Eventos entregues por ciclo. | `25` | Não |
| `EVENT_DELIVERY_MAX_ATTEMPTS` | Tentativas de entrega antes de um evento ser estacionado. | `3` | Não |
| `EVENT_DELIVERY_RETRY_BACKOFF` | Backoff base entre tentativas de entrega (duração Go). | `30s` | Não |
| `DISPATCH_MAX_AUTO_ATTEMPTS` | Tentativas automáticas de dispatch antes de intervenção manual. | `8` | Não |
| `DISPATCH_RETRY_BACKOFF_CEILING` | Backoff máximo entre tentativas de dispatch (duração Go). | `30m` | Não |
## Aprovação (maker-checker)
Aprovação opcional por faixa de valor que controla a emissão STR. Desligada por padrão — uma tabela de faixas vazia permite que cada emissão prossiga em etapa única.
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ----------- |
| `APPROVAL_ALCADA_BANDS` | Faixas `maxExclusive:requiredSignatures` separadas por ponto e vírgula (ex: `10000.00:1;100000.00:2`). Vazio mantém a aprovação desligada. | — | Não |
| `APPROVAL_DEADLINE_WINDOW` | Por quanto tempo uma emissão estacionada pode aguardar (duração Go, limitada a 7 dias). | `24h` | Não |
| `APPROVAL_EXPIRY_ENABLED` | Executa a varredura em segundo plano que expira emissões estacionadas em atraso. | `true` | Não |
| `APPROVAL_EXPIRY_SWEEP_INTERVAL` | Intervalo da varredura (duração Go). | `1m` | Não |
## Rate limiting e idempotência
| Variável | Descrição | Padrão | Obrigatória |
| ----------------------------- | --------------------------------------------------------------- | ------ | ----------- |
| `RATE_LIMIT_IP_MAX` | Máximo de requisições por IP por janela. | `300` | Não |
| `RATE_LIMIT_IP_WINDOW` | Janela de rate-limit por IP (duração Go). | `1m` | Não |
| `RATE_LIMIT_KEY_MAX` | Máximo de requisições por chave de API por janela. | `100` | Não |
| `RATE_LIMIT_KEY_WINDOW` | Janela de rate-limit por chave (duração Go). | `1m` | Não |
| `IDEMPOTENCY_ENABLED` | Habilita a deduplicação por chave de idempotência. | `true` | Não |
| `IDEMPOTENCY_DEFAULT_TTL_SEC` | Por quanto tempo (segundos) uma chave de idempotência é retida. | `300` | Não |
## Systemplane e configuração de runtime
O Lerian SPB monta a API de administração de configuração de runtime do systemplane em `/v1/system` na porta principal; ela é apoiada pelo PostgreSQL, então operadores podem ler e alterar configurações recarregáveis a quente sem uma reinicialização. Consulte [Systemplane](/pt/reference/systemplane/overview) para a API, os namespaces e as permissões.
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ----------- |
| `SYSTEMPLANE_LISTEN_CHANNEL` | Canal `LISTEN`/`NOTIFY` do PostgreSQL ao qual o plano de configuração de runtime se inscreve para mudanças de configuração a quente. | Padrão do serviço | Não |
## Criptografia e segredos
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------- |
| `STR_PAYLOAD_ENCRYPTION_KEY` | Chave AES-256 codificada em base64 para criptografia em repouso dos payloads STR armazenados. Sensível. Obrigatória em produção/staging. | — | Em produção/staging |
| `WEBHOOK_SECRET_KEY` | Chave usada para criptografar os segredos de webhook armazenados. Sensível. Obrigatória em produção/staging. | — | Em produção/staging |
| `INBOUND_ALLOW_CLEARTEXT_FALLBACK` | Permite que o caminho de entrada aceite payloads não criptografados. Mantenha `false` em produção. | `false` | Não |
Nunca faça commit nem registre em log os valores de qualquer variável marcada como *Sensível* (senhas, tokens, PINs e chaves AES). Injete-os no momento do deploy através do seu gerenciador de segredos.
## Observabilidade
| Variável | Descrição | Padrão | Obrigatória |
| ----------------------------- | ----------------------------------------------------------------------------- | ----------------------- | ------------------------ |
| `ENABLE_TELEMETRY` | Habilita tracing e métricas OpenTelemetry. | `false` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. | `http://localhost:4318` | Se telemetria habilitada |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço anexado à telemetria exportada. | Padrão do serviço | Não |
| `METRICS_PROMETHEUS_ENABLED` | Expõe um endpoint dedicado de scrape do Prometheus. | `false` | Não |
| `METRICS_PROMETHEUS_ADDRESS` | Endereço de escuta do endpoint Prometheus. Vincula-se ao loopback por padrão. | `127.0.0.1:9090` | Não |
## Apenas para desenvolvimento
Essas variáveis ampliam a superfície de ataque e são rejeitadas ou forçadas a desligado em produção/staging. Mantenha-as não definidas fora do desenvolvimento local.
| Variável | Descrição | Padrão | Obrigatória |
| --------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------- | ------------------- |
| `ENABLE_DEV_DEBUG_ROUTES` | Expõe rotas de debug. Proibido em produção/staging. | `false` | Não |
| `DEV_DEBUG_TOKEN` | Token que protege as rotas de debug. Sensível. Obrigatório quando as rotas de debug estão habilitadas. | — | Se debug habilitado |
| `SWAGGER_ENABLED` | Serve a spec OpenAPI e a UI de docs da API. Forçado a desligado em produção. | `false` | Não |
| `STR_MQ_MOCK` | Roteia o transporte STR para um mock em vez de um queue manager real. | `false` | Não |
| `STR_MQ_MOCK_HOST` | Host STR do mock. Obrigatório quando `STR_MQ_MOCK=true`. | `http://localhost:8080` | Se mock habilitado |
| `STR_MQ_MOCK_ALLOWED_HOSTS` | Allow-list de hosts que o transporte mock pode alcançar. | — | Não |
| `ALLOW_MOCK_TRANSPORT` | Permite que o transporte mock seja selecionado. | `false` | Não |
## Saúde e prontidão
O Lerian SPB expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta HTTP principal. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o contrato das probes.