# Variaveis de Ambiente

Referencia completa de todas as variaveis de ambiente utilizadas pelo Monetarie PIX, organizadas por categoria.

## Pre-requisitos

- Acesso ao servidor ou cluster Kubernetes onde o Monetarie PIX sera implantado
- Permissao para criar/editar ConfigMaps e Secrets no namespace `pix`
- Conhecimento basico de variaveis de ambiente em containers Docker/K8s

## Precedencia de Configuracao

O Monetarie PIX utiliza o sistema de configuracao do Elixir/Phoenix com a seguinte ordem de precedencia (maior prioridade primeiro):

```mermaid
flowchart LR
    A["Variaveis de Ambiente<br/>(maior prioridade)"] --> B["runtime.exs<br/>(execucao)"]
    B --> C["prod.exs / dev.exs<br/>(ambiente)"]
    C --> D["config.exs<br/>(base)"]
```

1. **Variaveis de ambiente** -- sempre tem prioridade maxima
2. **`config/runtime.exs`** -- executado em tempo de execucao (inclusive em releases)
3. **`config/prod.exs`** ou **`config/dev.exs`** -- configuracao por ambiente
4. **`config/config.exs`** -- configuracao base compartilhada

::: warning IMPORTANTE
Em modo release (producao), apenas `runtime.exs` e executado. As variaveis de ambiente definidas neste arquivo sao a unica forma de configurar o sistema em producao.
:::

## Banco de Dados

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `DATABASE_URL` | - | Nao* | URL completa de conexao PostgreSQL (`postgres://user:pass@host:port/db`). Se definida, sobrescreve as variaveis individuais abaixo |
| `DB_HOST` | `localhost` | Sim (prod) | Endereco do servidor PostgreSQL |
| `DB_PORT` | `5432` | Nao | Porta do PostgreSQL |
| `DB_USER` | `postgres` | Sim (prod) | Usuario do banco de dados |
| `DB_PASS` | `postgres` | Sim (prod) | Senha do banco de dados |
| `DB_NAME` | `monetarie` | Nao | Nome do banco de dados |
| `POOL_SIZE` | `250` | Nao | Tamanho do pool de conexoes **por repositorio** |
| `DATABASE_SSL` | `false` | Nao | Habilitar SSL na conexao com o banco |
| `ECTO_IPV6` | `false` | Nao | Habilitar IPv6 para conexao com o banco |

::: tip POOL_SIZE
O valor padrao de 250 conexoes e **por repositorio**. Com 4 repositorios (Shared, Dict, SPI, Settlement), o total e `250 x 4 = 1000` conexoes por pod. Com 2 pods, sao 2.000 conexoes. O Cloud SQL deve ter `max_connections >= 2200`.
:::

::: danger CARACTERES ESPECIAIS NA SENHA
Se a senha do banco contiver caracteres especiais, use URL encoding em `DATABASE_URL`:
- `/` -> `%2F`
- `=` -> `%3D`
- `@` -> `%40`
- `#` -> `%23`
:::

## Redis

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `REDIS_HOST` | `localhost` | Sim (prod) | Endereco do servidor Redis |
| `REDIS_PORT` | `6379` | Nao | Porta do Redis |

## NATS JetStream

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `NATS_HOST` | `localhost` | Sim (prod) | Endereco do servidor NATS |
| `NATS_PORT` | `4222` | Nao | Porta do NATS |
| `NATS_USER` | - | Nao | Usuario para autenticacao NATS |
| `NATS_PASS` | - | Nao | Senha para autenticacao NATS |
| `NATS_ENABLED` | `false` | Nao | Habilitar workers NATS JetStream. Defina como `true` em producao |

::: warning NATS_ENABLED
Por padrao os workers NATS estao desabilitados. Em producao, defina `NATS_ENABLED=true` para ativar os workers SPI (InboundProcessor, OutboundSender, StatusUpdater, ReturnProcessor) e o CoreEventProcessor.
:::

## Autenticacao e Seguranca

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `SECRET_KEY_BASE` | - | **Sim** | Chave secreta do Phoenix para cookies e sessoes. Gere com `mix phx.gen.secret` |
| `JWT_SECRET` | - | Nao | Chave para assinatura JWT. Fallback: `GUARDIAN_SECRET_KEY` -> `SECRET_KEY_BASE` |
| `GUARDIAN_SECRET_KEY` | - | Nao | Chave compartilhada com Core Banking (Guardian HS256). Obrigatorio para integracao Core |

A cadeia de fallback para o segredo JWT e:

```
JWT_SECRET  -->  GUARDIAN_SECRET_KEY  -->  SECRET_KEY_BASE
```

::: tip DESENVOLVIMENTO LOCAL COM CORE
Para testes locais de integracao com Core Banking, defina `JWT_SECRET` com o valor `"dev-only-secret-key-not-for-production"` (segredo de desenvolvimento do Core).
:::

## BACEN (Banco Central)

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `BACEN_ENV` | `homolog` | Nao | Ambiente BACEN: `homolog` ou `production` |
| `BACEN_ENABLED` | `false` | Nao | Habilitar integracao real com BACEN via RSFN |
| `BACEN_ISPB` | `00000000` | Sim (prod) | Codigo ISPB da instituicao (8 digitos) |
| `BACEN_PARTICIPANT_NAME` | `MONETARIE` | Nao | Nome curto do participante |
| `BACEN_CNPJ` | - | Sim (prod) | CNPJ da instituicao |
| `BACEN_CA_CERT_PATH` | - | Sim (prod) | Caminho para o certificado CA raiz do BACEN |
| `BACEN_CLIENT_CERT_PATH` | - | Sim (prod) | Caminho para o certificado ICP-Brasil da instituicao (CPIC) |
| `BACEN_CLIENT_KEY_PATH` | - | Sim (prod) | Caminho para a chave privada do certificado |
| `BACEN_CLIENT_KEY_PASSWORD` | - | Nao | Senha da chave privada (se criptografada) |
| `BACEN_TIMEOUT` | `30000` | Nao | Timeout de conexao com BACEN em milissegundos |
| `BACEN_FAILOVER_ENABLED` | `true` | Nao | Habilitar failover automatico entre canais CPM/CSM |
| `BACEN_FAILURE_THRESHOLD` | `3` | Nao | Numero de falhas consecutivas antes de marcar canal como inativo |
| `BACEN_HEALTH_CHECK_INTERVAL` | `30` | Nao | Intervalo de verificacao de saude do canal (segundos) |

## Simulador

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `SIMULATOR_ENABLED` | `false` | Nao | Habilitar simulador BACEN PIX. Nao use em producao |

::: danger SIMULADOR EM PRODUCAO
**Nunca** habilite `SIMULATOR_ENABLED=true` em producao. O simulador sobrescreve o comportamento real de comunicacao com o BACEN.
:::

## Servicos Internos

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `DICT_SERVICE_URL` | `http://localhost:4001` | Nao | URL interna do servico DICT (usada pelo CoreEventProcessor) |
| `SPI_SERVICE_URL` | `http://localhost:4002` | Nao | URL interna do servico SPI |
| `DICT_HOST` | `localhost` | Nao | Host do endpoint DICT |
| `DICT_PORT` | `4001` | Nao | Porta do endpoint DICT |
| `SPI_HOST` | `localhost` | Nao | Host do endpoint SPI |
| `SPI_PORT` | `4002` | Nao | Porta do endpoint SPI |
| `SETTLEMENT_HOST` | `localhost` | Nao | Host do endpoint Settlement (gateway API) |
| `SETTLEMENT_PORT` | `4003` | Nao | Porta do endpoint Settlement (gateway API) |

## Aplicacao

| Variavel | Padrao | Obrigatorio | Descricao |
|----------|--------|-------------|-----------|
| `PHX_HOST` | - | Nao | Hostname publico para geracao de URLs |
| `PHX_PORT` | `443` | Nao | Porta publica (HTTPS) |
| `MIX_ENV` | `dev` | Sim (prod) | Ambiente Elixir: `dev`, `test` ou `prod` |
| `RELEASE_NAME` | `monetarie_pix` | Nao | Nome do release Elixir |

## Exemplo Completo para Producao

```bash
# === Banco de Dados ===
export DB_HOST="10.140.241.2"
export DB_PORT="5432"
export DB_USER="monetarie_prod"
export DB_PASS="SenhaSegura123"
export DB_NAME="monetarie"
export POOL_SIZE="250"

# === Redis ===
export REDIS_HOST="10.140.240.4"
export REDIS_PORT="6379"

# === NATS ===
export NATS_HOST="10.10.40.5"
export NATS_PORT="4222"
export NATS_ENABLED="true"

# === Autenticacao ===
export SECRET_KEY_BASE="$(mix phx.gen.secret)"
export GUARDIAN_SECRET_KEY="chave-compartilhada-com-core"

# === BACEN ===
export BACEN_ENV="homolog"
export BACEN_ENABLED="true"
export BACEN_ISPB="12345678"
export BACEN_CNPJ="12345678000199"
export BACEN_CA_CERT_PATH="/certs/bacen-ca.pem"
export BACEN_CLIENT_CERT_PATH="/certs/cpic.pem"
export BACEN_CLIENT_KEY_PATH="/certs/cpic-key.pem"

# === Servicos ===
export DICT_SERVICE_URL="http://localhost:4001"
export SPI_SERVICE_URL="http://localhost:4002"
```

## Configuracao Kubernetes (Secrets)

Em Kubernetes, segredos sao armazenados em objetos Secret com chaves em **kebab-case**:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
  namespace: pix
type: Opaque
stringData:
  database-url: "postgres://monetarie_prod:SenhaSegura@10.140.241.2:5432/monetarie"
  secret-key-base: "sua-chave-secreta-aqui"
```

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: monetarie-shared-jwt-secret
  namespace: pix
type: Opaque
stringData:
  jwt-secret: "chave-compartilhada-com-core-banking"
```

::: warning CHAVES KEBAB-CASE
As chaves dos Secrets Kubernetes usam **kebab-case** (`database-url`, `secret-key-base`), nao SCREAMING_SNAKE_CASE. O `backend.yaml` faz o mapeamento para as variaveis de ambiente corretas.
:::

## Gerenciamento de Segredos

### Recomendacoes

1. **Nunca** armazene segredos em arquivos de configuracao versionados
2. Use **K8s Secrets** para ambientes Kubernetes
3. Para ambientes corporativos, considere:
   - **HashiCorp Vault** com o operador Kubernetes
   - **GCP Secret Manager** com workload identity
   - **AWS Secrets Manager** com IRSA
4. Rotacione `SECRET_KEY_BASE` e `GUARDIAN_SECRET_KEY` periodicamente
5. Use senhas fortes para o banco de dados (minimo 32 caracteres, alfanumerico + especiais)

### Verificacao de Configuracao

Apos definir todas as variaveis, verifique a configuracao:

```bash
# Em desenvolvimento
cd backend
mix phx.server

# Em Kubernetes (verificar logs do pod)
kubectl logs -n pix deployment/pix-backend --tail=50

# Verificar se todos os servicos iniciaram
# Procure por: "=== Starting Shared Application ===" nos logs
```

## Resultado Esperado

Apos configurar todas as variaveis obrigatorias:

- O backend inicia sem erros, exibindo `"=== Starting Shared Application (postgrex 0.16.x) ==="` nos logs
- Todos os 4 endpoints HTTP respondem (DICT:4001, SPI:4002, Settlement:4003)
- Se `NATS_ENABLED=true`, os workers SPI e CoreEventProcessor estao ativos
- Se `BACEN_ENABLED=true`, a conexao mTLS com BACEN e estabelecida
- O health check em `GET /health` retorna status 200