> ## 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 SILOC: runtime, conectividade com a fila de liquidação do SILOC, persistência, autenticação e certificados. O Lerian SILOC é a integração de mensageria nativa da Lerian para o SILOC, o sistema de liquidação diferida líquida que a Núclea opera para fluxos de boleto e cartão. Você define essas variáveis no momento do deploy. Uma alteração apenas entra em vigor depois que você reinicia o serviço. Para os parâmetros que se comportam da mesma forma em todo serviço Go da Lerian (postura de deployment, telemetria e convenções de datastore), consulte [Fundamentos de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md). Nas tabelas abaixo, **Obrigatório** marca uma variável que você deve definir, de forma global ou sob a condição indicada. `—` significa que não há padrão. ## Runtime e servidor | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `SERVICE_NAME` | Identificador do serviço usado em logs e telemetria. | Padrão do serviço | Não | | `ENV_NAME` | Rótulo do ambiente de runtime. `production` ou `prod` ativa os controles mais rígidos de autenticação e TLS descritos abaixo. | `development` | Não | | `DEPLOYMENT_MODE` | Postura de aplicação de TLS (`local`, `byoc`, `saas`). `saas` torna o TLS obrigatório, exige um `ENV_NAME` de produção e recusa iniciar sem eles. Consulte [Modo de deploy e TLS](https://docs.lerian.studio/pt/reference/byoc-configuration.md#deployment-mode-and-tls). | — | Não | | `LOG_LEVEL` | Verbosidade de log (`debug`, `info`, `warn`, `error`). | `info` | Não | | `SERVER_PORT` | Porta de escuta HTTP. Os probes de liveness e readiness usam essa mesma porta. | `9820` | Não | | `IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY` | Chave AES-256 que criptografa as respostas que o serviço guarda para replays de `X-Idempotency`: 32 bytes brutos, ou sua forma em base64. Sensível. | — | Sim | ## Licença O Lerian SILOC recusa iniciar sem uma licença da Lerian, em todos os ambientes. Nenhum ajuste desliga a verificação. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `LICENSE_KEY` | Chave de licença da Lerian. Sensível. | — | Sim | | `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`. | — | Não | ## Autenticação O Lerian SILOC autoriza rotas protegidas por meio do Access Manager. `AUTH_ENABLED` não tem padrão, então o serviço recusa iniciar até que você o defina. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `AUTH_ENABLED` | Exige autorização do Access Manager nas rotas protegidas: `true` ou `false`. Qualquer outro valor impede o serviço de iniciar. O serviço aceita `false` apenas quando você define `ENV_NAME` como `development`, `develop`, `dev`, `local` ou `test`, e nunca com `DEPLOYMENT_MODE=saas`. Com `false`, o serviço pula a chamada ao Access Manager, mas ainda exige um bearer token. | — | Sim | | `AUTH_ADDRESS` | Endereço do serviço Access Manager. Deve ser uma URL `https://` válida em produção e no SaaS. Com a autorização ativa e sem endereço, as rotas protegidas respondem 503. | — | Em produção e no SaaS | ## PostgreSQL A réplica volta a usar o host primário quando você deixa `DB_REPLICA_HOST` vazio (padrão de nó único). | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `DB_HOST` | Host do PostgreSQL. | — | Sim (em operação real) | | `DB_PORT` | Porta do PostgreSQL. | `5432` | Não | | `DB_USER` | Usuário do banco de dados. | — | Sim (em operação real) | | `DB_PASSWORD` | Senha do banco de dados. Sensível. Injete-a no momento do deploy e nunca faça commit dela. | — | Sim (em operação real) | | `DB_NAME` | Nome do banco de dados. | — | Sim (em operação real) | | `DB_SSLMODE` | Modo de TLS do libpq. Um modo diferente de `require`, `verify-ca` ou `verify-full` exige `ALLOW_INSECURE_TLS=true`. | `disable` | Não | | `DB_REPLICA_HOST` | Host opcional de réplica de leitura. Volta a usar `DB_HOST` quando não definido. | — | Não | ## Redis | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `REDIS_ADDRESS` | Host e porta do Redis/Valkey. O gate de `X-Idempotency` guarda suas chaves aqui, então as requisições que alteram estado e o readiness precisam dele. | — | Sim (em operação real) | | `REDIS_PASSWORD` | Senha do Redis. Sensível. | — | Não | | `REDIS_DB` | Número do banco de dados Redis. Um valor que não seja inteiro recusa iniciar. | `0` | Não | | `REDIS_TLS` | Abre a conexão com o Redis sobre TLS. `DEPLOYMENT_MODE=saas` exige `true`. | `false` | Não | | `REDIS_CA_CERT` | Autoridade certificadora PEM codificada em base64 que valida o servidor Redis quando `REDIS_TLS=true`. Quando ela está vazia, o serviço usa as autoridades confiáveis do sistema operacional. | — | Não | | `ALLOW_INSECURE_TLS` | Defina true para o serviço abrir conexões com PostgreSQL e Redis sem TLS. O serviço registra um aviso enquanto essa exceção estiver ativa. | — | Não | ## Conectividade de liquidação do SILOC O Lerian SILOC mantém uma única conexão IBM MQ com o gerenciador de filas de liquidação do SILOC na Núclea. Definir `MQ_HOST`, `MQ_CHANNEL`, `MQ_QUEUE_MANAGER`, `MQ_SEND_QUEUE` ou `MQ_RECEIVE_QUEUE` faz o serviço validar todo o descritor de conexão de forma fail-closed na inicialização. Sozinhas, as demais variáveis `MQ_*` não ativam essa validação. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `LOCAL_FI_ISPB` | O ISPB de 8 dígitos desta instituição. Toda mensagem OT é autorizada contra ele. Com o MQ configurado, ele deve corresponder ao ISPB em `MQ_CHANNEL`. | — | Sim | | `MQ_HOST` | Host do gerenciador de filas. | — | Sim (SILOC em operação real) | | `MQ_PORT` | Porta de escuta do gerenciador de filas. | — | Sim (SILOC em operação real) | | `MQ_QUEUE_MANAGER` | Nome do gerenciador de filas. Deve ser o gerenciador de filas de liquidação do SILOC na Núclea. | — | Sim (SILOC em operação real) | | `MQ_CHANNEL` | Canal de conexão do servidor. Deve corresponder ao padrão de canal do SILOC na Núclea `C02992335..1`, em que `` é o ISPB de 8 dígitos do participante. | — | Sim (SILOC em operação real) | | `MQ_SEND_QUEUE` | Fila de envio de saída. | — | Sim (SILOC em operação real) | | `MQ_RECEIVE_QUEUE` | Fila de recebimento de entrada. | — | Sim (SILOC em operação real) | | `MQ_BACKOUT_THRESHOLD` | Quantas vezes o serviço pode recusar um frame de entrada antes de estacioná-lo em seu banco de dados e retirá-lo da fila de recebimento. Um inteiro de 1 a 1000. | — | Sim (SILOC em operação real) | | `MQ_BACKOUT_DELAY` | Pausa antes de um frame recusado ser entregue novamente, como uma duração com unidade, de `100ms` a `1m` (por exemplo, `2s`). | — | Sim (SILOC em operação real) | | `MQ_TLS_ENABLED` | Habilita o TLS mútuo no canal MQ. Deve ser `true` em produção e no SaaS. | `false` | Em produção e no SaaS | | `MQ_SSL_KEY_REPOSITORY` | Caminho do repositório de chaves do GSKit (`MQSSLKEYR`) que sustenta o TLS do MQ. A chave privada fica aqui, nunca em uma variável de ambiente. Obrigatório quando `MQ_TLS_ENABLED=true`. | — | Se TLS habilitado | | `MQ_CIPHER_SPEC` | Especificação de cifra TLS do canal MQ quando `MQ_TLS_ENABLED=true`. Deve corresponder à especificação de cifra do canal de conexão do servidor no gerenciador de filas. | `ECDHE_RSA_AES_256_CBC_SHA384` | Não | | `MQ_CERT_LABEL` | Rótulo do certificado no repositório de chaves que o serviço apresenta no canal MQ quando `MQ_TLS_ENABLED=true`. Quando ele está vazio, o cliente MQ usa seu rótulo padrão. | — | Não | | `CAMARA_PAG_ISPB` | O ISPB de 8 dígitos da câmara do SILOC. Toda mensagem de liquidação de entrada é autorizada contra esse remetente antes de ter qualquer efeito semântico. Ele corresponde ao prefixo do canal de liquidação, então apenas substitua esse valor para uma câmara de teste. Um valor que não tenha 8 dígitos recusa iniciar. | `02992335` | Não | ## Mensagens de saída O serviço envia as requisições da instituição à Núclea apenas quando os dois identificadores de certificado e `MQ_SEND_QUEUE` estão definidos. Defina os dois identificadores ou nenhum: um sem o outro recusa iniciar. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `SFN_OUTBOUND_SIGNER_CERT_ID` | O certificado que assina as mensagens de saída, no formato `:<64 hex>`. O provedor de custódia guarda sua chave. Um valor que não é interpretado impede o serviço de iniciar. Uma nova requisição de saída é recusada com 503 `SILOC-0024` enquanto esse certificado não está registrado, está revogado ou fora da validade, ou não corresponde à chave da custódia. | — | Para enviar | | `SFN_CAMARA_CERT_ID` | O certificado da câmara, do manifesto de confiança, para o qual as mensagens de saída são criptografadas, no mesmo formato. Um valor que não é interpretado impede o serviço de iniciar. Uma nova requisição de saída é recusada com 503 `SILOC-0024` enquanto esse certificado está ausente do repositório de confiança, revogado ou fora da validade. | — | Para enviar | | `OT_OUTBOUND_DISPATCH_INTERVAL` | Com que frequência o dispatcher coloca as mensagens enviadas na fila de envio. | `5s` | Não | | `UNANSWERED_REQUEST_DEADLINES` | Quanto tempo uma requisição despachada aguarda sua resposta antes de o serviço gerar `UNANSWERED_REQUEST`, no formato `default=,=`. Sem definição, consultas aguardam 2 minutos, confirmações 5 e comandos 15. O mínimo é 1 segundo. | — | Não | | `UNANSWERED_REQUEST_SWEEP_INTERVAL` | Com que frequência o serviço verifica requisições sem resposta, de `1s` a `10m`. | `30s` | Não | ## Validação de mensagens O serviço valida as mensagens de entrada que aplica e as mensagens de saída que envia contra os schemas XSD oficiais, por meio de um sidecar validador. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `XSD_VALIDATOR_URL` | URL base do sidecar validador. | — | Sim (SILOC em operação real) | | `XSD_VALIDATOR_TIMEOUT_SEC` | Timeout de uma requisição de validação, em segundos. Um valor que não seja inteiro recusa iniciar. | `10` | Não | O sidecar escuta em `XSD_VALIDATOR_ADDR` (padrão `127.0.0.1:9091`), e o seu próprio `AUTH_ENABLED` não tem padrão. O serviço não envia bearer token ao sidecar, então execute o sidecar com `AUTH_ENABLED=false` em um endereço de loopback literal. ## Certificados | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `CERT_READINESS_MIN_DAYS` | Limite de dias até o vencimento abaixo do qual um certificado atualmente válido registra um aviso e gera um alerta `CERTIFICATE_EXPIRY`. Não degrada o readiness apenas porque o certificado está perto do vencimento. Deve ser um inteiro maior que 0. | `30` | Não | ## Confiança e custódia | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `SFN_TRUST_MANIFEST_PATH` | Caminho do manifesto de confiança do SFN usado para validar o material de confiança de mensagens regulatórias. Sem ele, o serviço informa que não está pronto. | — | Sim (SILOC em operação real) | | `SFN_CUSTODY_CONFIG_PATH` | Caminho da configuração do provedor de custódia. Sem ele, o serviço informa que não está pronto. Quando o serviço abre um provedor `kmip`, ele assina um digest de teste, e um provedor cuja chave de assinatura não consegue assiná-lo também informa que não está pronto. | — | Sim (SILOC em operação real) | | `SFN_CUSTODY_CACHE_ENTRIES` | Número máximo de entradas de custódia mantidas no cache em memória. Um valor que não seja inteiro recusa iniciar. | `16` | Não | ## Processamento em segundo plano As cinco chaves `*_ENABLED` desta tabela não têm padrão. Defina cada uma como `true` ou `false`, porque um valor em branco recusa iniciar. Com `false`, o runtime fica desligado e sua verificação de readiness informa `skipped`. Com `true`, o serviço tenta de novo um runtime que falha ao iniciar até que ele rode, e sua verificação de readiness informa o motivo sem falhar. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `OT_REPLAY_ENABLED` | Aplica as mensagens de entrada estacionadas, exceto `PAG0101`: mensagens de ciclo OT, avisos da câmara e respostas às requisições da instituição. Com `true`, a conexão MQ do SILOC (`MQ_HOST` e o restante de `MQ_*`) deve estar configurada, ou o serviço se recusa a iniciar e nomeia as duas configurações. | — | Sim | | `OT_REPLAY_INTERVAL` | Com que frequência o replay de OT roda. | `10s` | Não | | `STATUS_REPLAY_ENABLED` | Aplica as mensagens de status de participante `PAG0101` estacionadas. | — | Sim | | `STATUS_REPLAY_INTERVAL` | Com que frequência o replay de status roda. | `10s` | Não | | `RECONCILE_ENABLED` | Concilia os ciclos OT com o resultado multilateral `GEN0015` da câmara e liquida um ciclo cujo resultado corresponde à sua obrigação. | — | Sim | | `RECONCILE_INTERVAL` | Com que frequência a conciliação roda. | `10s` | Não | | `LDL_FACT_CONSUMER_ENABLED` | Consome os fatos de liquidação LDL do SPB. Cada fato registra o resultado da instrução que ele nomeia. | — | Sim | | `CARD_COMMAND_CONSUMER_ENABLED` | Consome comandos de cartão do Lerian SLC e os envia à Núclea. | — | Sim | ## Declaração de permissões O serviço 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 publicação ativa, uma variável ausente abaixo recusa iniciar. | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `IDP_DECLARATION_ENABLED` | Publica o conjunto de permissões na inicialização. | `false` | Não | | `IDP_HOST` | URL base do Access Manager para a qual o conjunto é publicado. Deve ser `https://` fora de ambientes locais e de desenvolvimento. | — | Com declaração | | `IDP_M2M_CLIENT_ID` | Client ID da aplicação máquina a máquina do serviço, cujo nome deve ser `siloc`. | — | Com declaração | | `IDP_M2M_CLIENT_SECRET` | Client secret dessa aplicação. Sensível. | — | Com declaração | | `PLUGIN_AUTH_ENABLED` | Deve ser `true` para que o serviço obtenha o token que a publicação usa. Qualquer valor diferente de `true` ou `false` impede o serviço de iniciar. Não controla a autorização de rotas, que é o papel de `AUTH_ENABLED`. | — | Com declaração | | `PLUGIN_AUTH_HOST` | Endereço do Access Manager para esse token. | — | Com declaração | ## Observabilidade | Variável | Descrição | Padrão | Obrigatório | | - | - | - | - | | `ENABLE_TELEMETRY` | Habilita a instrumentação do OpenTelemetry. | `false` | Não | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. | — | Se telemetria habilitada | | `STREAMING_BROKERS` | Endereços dos brokers para o dispatcher obrigatório de fatos do SILOC. O streaming não tem modo desabilitado: uma configuração de broker ausente ou inválida impede a inicialização, em vez de deixar os fatos como `PENDING`. Configure as opções compartilhadas `STREAMING_*` conforme descrito em [Streaming e outbox](https://docs.lerian.studio/pt/reference/byoc-configuration.md#streaming-and-outbox). | — | Sim | | `STREAMING_CLOUDEVENTS_SOURCE` | Identidade de origem do CloudEvents. Deve ser exatamente `br-siloc`. Um valor diferente, incluindo espaços em branco no início ou no fim, impede a inicialização; o serviço usa essa identidade para derivar os tópicos de broker e o escopo de controle de acesso. | — | Sim | Se `STREAMING_EVENT_POLICIES` define `enabled=false` para qualquer evento de fato do SILOC, o serviço recusa iniciar. Se define `enabled=false` para um evento de comando de cartão (`siloc_command.accepted`, `siloc_command.answered`, `siloc_command.refused` ou `siloc_command.failed`), o consumidor de comandos de cartão não inicia. Se define `enabled=false` para `siloc.relay.inbound`, o processamento de mensagens de entrada não inicia. Nos dois casos, o erro nomeia o evento. ## Health e readiness O Lerian SILOC expõe `GET /health` (liveness), `GET /readyz` (readiness) e `GET /version` na porta HTTP principal. O serviço recusa iniciar quando o PostgreSQL não responde em até 10 segundos. Ele inicia antes que o Redis e a conexão de liquidação estejam acessíveis. `/readyz` informa a saúde de cada dependência. Enquanto o queue manager do SILOC da Núclea não está acessível, `siloc-mq` informa `down` e não faz o `/readyz` passar a 503. `siloc-mq` reprova o readiness quando o queue manager recusa a configuração deste deploy, e nomeia o ajuste a corrigir. `/readyz` também reporta uma verificação `license`. Com `LICENSE_KEY`, a verificação não faz nenhuma chamada e aparece como no ar. Uma licença que deixa de ser válida após a inicialização não leva `/readyz` a 503. As verificações `certificate` e `sfn-trust-store` reportam sem fazer `/readyz` falhar, então um serviço em execução continua em rotação. A verificação `certificate` aparece como down quando não resta nenhum certificado local válido no momento, ou quando a custódia não responde. A verificação `sfn-trust-store` aparece como degraded quando não resta nenhum certificado de remetente confiável utilizável. Uma falha de composição da custódia ou do manifesto de confiança ainda faz `/readyz` falhar. Crie alertas sobre essas verificações, porque `/readyz` sozinho não sinaliza um certificado expirado. Consulte [Health e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato de probe. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.