# Deploy — API (VPS da FLS)

Ambiente: **VPS Hostinger** (Debian 13), **Podman rootless + Quadlet**, **Caddy**
(proxy + TLS), user `admin`.
No ar: **https://api-scardua.flstecnologia.tech**

> ℹ️ O nome `api-scardua` é **legado** — a API hoje atende múltiplos clientes
> (`/v1/holmes/{cliente}/...`). Renomear implica mexer junto em: nome do quadlet,
> `Image=`, `ContainerName=`, pasta do `configs.json`, build dir, bloco do
> Caddyfile e DNS. O `reverse_proxy` do Caddy resolve o container pelo
> `ContainerName` dentro da rede `fls` — se um mudar sem o outro, dá **502**.

## Acesso à VPS

```bash
ssh vps-fls          # alias -> 179.197.230.154, porta 3115, user admin
```

- Porta 22 é **fechada** no firewall. Sempre `-p 3115` (ou o alias).
- `systemctl --user` sempre (rootless) — **nunca** `sudo systemctl` pros containers.
- ⚠️ O `~/.ssh/config` tem um **BOM** na primeira linha e o OpenSSH do Git Bash
  recusa (`Bad configuration option: \357\273\277host`). Contorno sem editar o
  arquivo:
  ```bash
  ssh -F none -i ~/.ssh/id_ed25519 -p 3115 admin@179.197.230.154
  ```

## Arquitetura

- Imagem: buildada **local na VPS** = `localhost/api-scardua:latest` (sem registry).
- Container na rede **`fls`** — só o Caddy alcança; a porta 8000 **não** é publicada.
- Config: `configs.json` montado read-only de `~/.config/api-scardua/configs.json`.
- Quadlet: `~/.config/containers/systemd/api-scardua.container`.
- Caddy: `api-scardua.flstecnologia.tech` → `api-scardua:8000`, TLS automático.
  Caddyfile em `/srv/containers/stacks/caddy/Caddyfile`.

## Atualizar a app

```bash
# 1. marcar rollback ANTES de qualquer coisa
ssh vps-fls 'podman tag localhost/api-scardua:latest localhost/api-scardua:rollback-$(date +%F)'

# 2. mandar o código (não tem rsync no Git Bash do Windows; tar resolve)
tar czf - --exclude='__pycache__' --exclude='*.pyc' --exclude='.ruff_cache' \
    main.py app requirements.txt Dockerfile .dockerignore pyproject.toml \
  | ssh vps-fls 'rm -rf ~/build/api-scardua && mkdir -p ~/build/api-scardua && tar xzf - -C ~/build/api-scardua'

# 3. buildar e reiniciar
ssh vps-fls 'cd ~/build/api-scardua && podman build --format docker -t api-scardua:latest . \
             && systemctl --user restart api-scardua'
```

> ⚠️ **`--format docker` é obrigatório.** No formato OCI (padrão do Podman) o
> `HEALTHCHECK` do Dockerfile é **silenciosamente ignorado** — e é ele que o
> `podman auto-update` usa pra decidir rollback. Conferir depois do build:
> ```bash
> podman inspect localhost/api-scardua:latest --format '{{json .HealthCheck}}'
> ```

> ⚠️ Diretórios da build antiga podem estar **sem bit de escrita** (`dr-x------`)
> e travar o `rm -rf` no meio. Se acontecer: `chmod -R u+rwX ~/build/api-scardua`.

## O configs.json da VPS é separado

Ele **não** vem do repo (gitignored). Vive em `~/.config/api-scardua/configs.json`
e tem que ser atualizado à mão quando o formato do `Settings` mudar — senão o
container entra em **crash-loop** na validação do Pydantic, que roda no import.

```bash
cat configs.json | ssh vps-fls 'cat > ~/.config/api-scardua/configs.json && chmod 600 $_'
```

## Rollback

```bash
ssh vps-fls '
  podman tag localhost/api-scardua:rollback-<data> localhost/api-scardua:latest
  systemctl --user restart api-scardua
'
```

## Mexer no Caddy (com segurança)

```bash
cd /srv/containers/stacks/caddy
cp Caddyfile Caddyfile.bak
# editar...
podman exec caddy caddy validate --config /etc/caddy/Caddyfile   # valida ANTES
podman exec caddy caddy reload   --config /etc/caddy/Caddyfile   # sem downtime
```

## Comandos úteis

```bash
systemctl --user status api-scardua
podman logs -f api-scardua
podman ps --filter name=api-scardua        # estado + health
podman healthcheck run api-scardua
```

## Verificar depois de subir

```bash
curl -s -o /dev/null -w '%{http_code}\n' https://api-scardua.flstecnologia.tech/health
curl -X POST https://api-scardua.flstecnologia.tech/v1/holmes/scardua/compras/dados \
     -H 'Content-Type: application/json' -d @payload-do-holmes.json
```

Cliente desconhecido na rota deve dar **404** (`cliente 'x' nao atendido`).

## Evolução planejada

- **Registry + CI** (Forgejo Actions): publicar em `git.flstecnologia.tech`, trocar
  o Quadlet pro alvo com `AutoUpdate=registry` → deploy pull-based.
- Backup do Postgres da VPS (pendência geral do servidor).