⚙️ Preparação do Ambiente e Variáveis¶

Antes de iniciar o deploy, é necessário configurar as variáveis de ambiente que regem o comportamento da aplicação. O e-SUS AF utiliza uma gama extensa de configurações para suportar alta disponibilidade e integrações governamentais.

1. Variáveis do Servidor (API) 🖥️¶

A API (NestJS) consome variáveis de ambiente para gerenciar a conexão com infraestrutura e serviços externos.

1.1 Infraestrutura de Banco de Dados¶

Variável	Descrição	Padrão
`DB_DIALECT`	Dialeto do banco (mysql, mariadb, postgres, oracle)	`postgres`
`DB_HOST`	Host do servidor de banco de dados	`localhost`
`DB_PORT`	Porta do banco de dados	`5432`
`DB_USERNAME`	Usuário de acesso ao banco	`postgres`
`DB_PASSWORD`	Senha de acesso ao banco	-
`DB_DATABASE`	Nome do banco de dados/instância	`esusaf`
`DB_SCHEMA`	Schema principal do banco	`dbesusaf`
`DB_POOL_MAX`	Limite máximo do pool de conexões (Prisma ORM)	`20`
`DB_POOL_MIN`	Limite mínimo do pool de conexões (Prisma ORM)	`5`
`DB_LOGGING`	Ativar log de queries no banco de dados (`true` / `false`)	`false`
`DB_SSL_CERTPATH`	Caminho para o certificado SSL do banco (se houver)	-
`DB_SSL_REJECT_UNAUTHORIZED`	Se deve rejeitar certificados não assinados	`true`

1.2 Cache e Sessão (Redis)¶

Variável	Descrição	Padrão
`REDIS_HOST`	Host do Redis	`localhost`
`REDIS_PORT`	Porta do Redis	`6379`
`REDIS_PASSWORD`	Senha do Redis	-
`REDIS_TLS_ENABLED`	Ativar conexão via TLS/SSL	`false`
`REDIS_TLS_REJECT_UNAUTHORIZED`	Rejeitar certificados TLS não reconhecidos	`true`
`REDIS_CLUSTER_ENABLED`	Ativar suporte a Cluster Mode	`false`
`REDIS_CLUSTER_NODES`	Lista de nós (host:port,host:port)	-
`REDIS_CACHE_TIMEOUT_MS`	Timeout limite (ms) para operações de leitura/escrita no cache Redis	`200`
`REDIS_CACHE_INVALIDATE_TIMEOUT_MS`	Timeout limite (ms) para invalidação de cache por prefixo SCAN/DEL	`2000`
`ENABLE_STOCK_REPORT_CACHE`	Ativa cache-aside Redis para o relatório de posição de estoque (`true`/`false`)	`false`
`STOCK_REPORT_CACHE_TTL_SECONDS`	Tempo de vida (TTL em segundos) dos dados no cache do relatório de estoque	`300`

1.3 Segurança e Tokens (JWT)¶

Variável	Descrição	Exemplo/Padrão
`SECRET_KEY`	Chave secreta global para hash e criptografia	`chave_longa_aleatoria`
`KEY_PATH`	Pasta das chaves assimétricas ES512	`/app/chaves`
`JWT_EXPIRES_IN`	Tempo de expiração do Access Token	`15m`
`JWT_REFRESH_EXPIRES_IN`	Tempo de expiração do Refresh Token	`1h`

1.4 E-mail (SMTP)¶

Variável	Descrição	Exemplo
`MAIL_HOST`	Servidor SMTP de saída	`smtp.email.sa-saopaulo-1.oci.oraclecloud.com`
`MAIL_PORT`	Porta SMTP — `587` para STARTTLS, `465` para SSL implícito	`587`
`MAIL_USER`	Usuário de autenticação no servidor SMTP	`ocid1.user.oc1...`
`MAIL_PASS`	Senha de autenticação no servidor SMTP	-
`MAIL_FROM`	Endereço de remetente exibido nas mensagens	`no-reply.esusaf@dominio.gov.br`
`MAIL_SECURE`	`true` força SSL implícito (porta 465); `false` usa STARTTLS	`false`
`MAIL_PREVIEW_MODE`	Quando `true`, loga o e-mail no console em vez de enviá-lo (útil em dev)	`false`

1.5 Autenticação Gov.br¶

O e-SUS AF integra com o Login Único Gov.br via protocolo OIDC. O Gov.br disponibiliza dois ambientes — as credenciais (CLIENT_ID / CLIENT_SECRET) são emitidas separadamente para cada um pelo portal de gestão do Gov.br.

Variável	Descrição	Staging	Produção
`GOV_BR_PROVIDER`	Identificador do provedor OIDC	`govbr`	`govbr`
`GOV_BR_SERVICE`	Nome do serviço cadastrado no painel Gov.br	—	—
`GOV_BR_CLIENT_ID`	Client ID gerado no cadastro da aplicação	—	—
`GOV_BR_CLIENT_SECRET`	Client Secret gerado no cadastro da aplicação	—	—
`GOV_BR_SCOPE`	Escopos OIDC solicitados	`openid+email+profile`	`openid+email+profile`
`GOV_BR_CALLBACK_URL`	URL de retorno após autenticação (deve ser registrada no painel Gov.br)	`https://[dominio]/auth/callback/govbr`	`https://[dominio]/auth/callback/govbr`
`GOV_BR_LOGIN_ROUTE`	Rota interna que inicia o fluxo de redirecionamento	`/auth/login`	`/auth/login`
`GOV_BR_SSO_LOGOUT_URL`	URL de logout do SSO Gov.br	`https://sso.staging.acesso.gov.br/logout`	`https://sso.acesso.gov.br/logout`

1.6 Integrações de Saúde¶

Variáveis que controlam a comunicação com sistemas federais do Ministério da Saúde. Quando a integração não estiver habilitada no ambiente, os valores podem ser deixados como placeholders.

Variável	Descrição	Exemplo
`BIAF_URL`	URL base da API BIAF (Banco de Dados de Insumos da AF)	`BIAF_URL`
`BIAF_CLIENT_ID`	Client ID para autenticação na API BIAF	`BIAF_CLIENT_ID`
`BIAF_APIKEY`	API Key de acesso à API BIAF	`BIAF_APIKEY`
`BIAF_STATUS`	Habilita (`active`) ou desabilita (`inactive`) a integração BIAF	`BIAF_STATUS`
`SI_BNAFAR_BASE_URL`	URL base do SiBnafar — serviço de transmissão ao Ministério da Saúde	-
`SI_BNAFAR_AUTH_URL`	URL de autenticação do SiBnafar	-
`SOAP_LOG_PAYLOAD`	Log do corpo de chamadas SOAP (CNS/SiBnafar), truncado em 2048 chars (`1` para ativar; desativado por padrão)	`1`

1.7 Observabilidade (Telemetria)¶

Variável	Descrição	Exemplo / Padrão
`ENABLE_TELEMETRY`	Ativar OpenTelemetry (OTEL) e métricas Prometheus (`1` ativa)	`1`
`METRICS_EXPORTER_PORT`	Porta para raspagem do endpoint `/metrics` do Prometheus	`8081`
`SERVICE_NAME`	Nome do serviço para traces e métricas	`api_esusaf`
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Endpoint OTLP HTTP para exportação de traces	`http://localhost:4318/v1/traces`
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint de fallback OTLP do coletor OTEL	`http://otel:4317`
`TELEMETRY_COLLECTOR_URL`	URL alternativa do coletor de telemetria	-
`LOG_LEVEL`	Nível de log (`error`, `warn`, `info`, `debug`, `silly`)	`info`
`USE_JSON_LOGGER`	Formata logs como JSON estruturado (recomendado para coleta via OTEL)	`false`

1.8 Variáveis Gerais¶

Variável	Descrição	Padrão
`PORT`	Porta em que a API escuta	`3001`
`NODE_ENV`	Ambiente de execução (`production`, `development`)	`production`
`API_URL`	URL pública da API (usada em links gerados pelo servidor)	`https://esusaf.dominio.gov.br/api`
`CLIENT_LOGIN_ROUTE`	URL do frontend para redirecionamento pós-autenticação	`https://esusaf.dominio.gov.br`
`DEFAULT_PASSWORD`	Senha padrão gerada para novos usuários	-
`DEFAULT_LANGUAGE`	Idioma padrão da aplicação	`pt-BR`
`I18N_FALLBACK_LANGUAGE`	Idioma de fallback para internacionalização	`pt-BR`

2. Variáveis do Cliente (Web) 🌐¶

O frontend (Vite) utiliza placeholders injetados em tempo de execução no container Nginx. Para deploys em Docker/K8s, as variáveis devem seguir o prefixo VAR__.

Variável Runtime	Variável Interna (VITE)	Descrição	Exemplo
`VAR__API_URL`	`VITE_APP_API_URL`	URL pública da API e-SUS AF	`https://esusaf.ifpb.edu.br`
`VAR__AMBIENTE_ESUS`	`VITE_AMBIENTE_ESUS`	Identidade visual/rotas: `pr` (Produção), `tr` (Treino), `hm` (Homol), `dv` (Dev). Para desativar o módulo de oncologia, utilizar `pr`.	`pr`
`VAR__APP_STATUS`	`VITE_APP_STATUS`	`active`, `maintenance` ou `construction`	`active`
`VAR__FORCE_PROD_MODE`	`VITE_APP_FORCE_PROD_MODE`	Força comportamento de produção (`true`/`false`)	`false`
`VAR__CONTEXT`	-	Caminho base da URL (ex: `/portal`)	—
`VAR__GOV_BR_LOGOUT_URL`	`VITE_APP_GOV_BR_LOGOUT_URL`	URL de logout do SSO Gov.br — staging ou produção conforme o ambiente	`https://sso.staging.acesso.gov.br/logout`
`VAR__GOV_BR_LOGOUT_CALLBACK_ROUTE`	`VITE_APP_GOV_BR_LOGOUT_CALLBACK_ROUTE`	URL completa de retorno após o logout Gov.br (deve ser registrada no painel Gov.br)	`https://esusaf.ifpb.edu.br/auth/callback/govbrlogout`
`VAR__TIMEOUT_CHECK_INTERVAL_MS`	`VITE_TIMEOUT_CHECK_INTERVAL_MS`	Intervalo (ms) para verificação de timeout de sessão	—

3. Criptografia Assimétrica e Réplicas 🔑¶

O e-SUS AF utiliza o algoritmo ES512 (Curva secp521r1) para assinar tokens JWT.

3.1 Compartilhamento entre Réplicas¶

Em ambientes com múltiplas instâncias da API, todas as réplicas devem obrigatoriamente ler as mesmas chaves.

Configuração: Defina a variável KEY_PATH e monte um volume compartilhado (PV/PVC ou Bind) contendo os arquivos private_key.pem e public_key.pem.

3.2 Geração Manual¶

# Gerar par de chaves ES512
openssl ecparam -name secp521r1 -genkey -noout -out private_key.pem
openssl ec -in private_key.pem -pubout -out public_key.pem