ruicesar/scoreodonto.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(version): versão em runtime via /api/version (Passos 1/3/4)

Browse Source 
- buildInfo.ts: hook useAppVersion() consome GET /api/version (fonte única = backend),
  com fallback ao carimbo do bundle; deixa de depender do APP_VERSION manual.
- Versão exibida em Configurações ("Sobre o sistema") + telas públicas (Login/WaitingInvite);
  removida do rodapé do Sidebar.
- compose.prod/deploy-prod.sh: injetam APP_VERSION (=tag) e APP_ENV=PROD em runtime,
  desacoplando a versão semântica do build (commit/build seguem da imagem).
- constants.ts marcado legado + bump V1.0.15 (transitório até o Passo 5; evita colisão de tag).
- DEPLOY-PRODUCAO.md reescrito com status ✅/🧪/🎯 + nota de fase transitória.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
VPS 4 Builder
2026-06-17 05:19:27 +02:00
parent 6e81718725
commit a991f1fe2c
9 changed files with 187 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentação/DEPLOY-PRODUCAO.md
+107 -135
View File
@@ -1,170 +1,142 @@
# DEPLOY-PRODUCAO — Runbook operacional
# Deploy & Versionamento — Runbook ScoreOdonto
> ✅ **FLUXO CANÔNICO HOJE: deploy por TAG (CI/CD).** Para subir uma versão à produção:
> ```
> # na VPS4, com a versão validada em dev:
> node update-version.js && git add -A && git commit -m "..." && git push origin main
> git tag v1.0.XX && git push origin v1.0.XX # ← a TAG dispara build + deploy automático na VPS1
> ```
> A CI builda a imagem versionada, publica no registry e promove para a VPS1 (`deploy-prod.sh`). Confirme em `https://scoreodonto.com/api/version`.
> **Rollback:** na VPS1, `./deploy-prod.sh <tag-anterior>`. Detalhes em `deploy.md` e `REGISTRY.md`.
> Auditado contra o sistema em **17/jun/2026**. Cada item carrega seu **status real** — o doc
> responde *"o que existe hoje?"*, não *"o que gostaríamos?"*.
>
> ⬇️ O passo a passo manual abaixo continua válido como **fallback** (deploy sem a CI).
---
> 🛑 Procedimento manual (fallback), passo a passo, sem adivinhação.
> Reflete o mecanismo de build local. A realidade da infra está em `arquitetura.md`; o fluxo por tag em `deploy.md`.
> **Legenda de status (convenção do projeto):**
> - ✅ **EM PRODUÇÃO** — está no ar em `scoreodonto.com` (VPS1), verificável agora.
> - 🧪 **EM DEV** — implementado no working tree da VPS4 / `dev.scoreodonto.com`; **não commitado, não promovido**.
> - 🎯 **ALVO** — desenhado/aprovado, **ainda não implementado**.
>
> ⚠️ **Regra de ouro:** antes de qualquer build/deploy/push, confirme com o operador **DEV ou PRODUÇÃO**.
> `dev.scoreodonto.com` = VPS4 (descartável, mas **mesmo banco** da prod). `scoreodonto.com` = VPS1 (real).
> **Nunca** `git push --force` na `main`. **Dev e prod compartilham o banco** (VPS3) — o backup é a única rede de segurança.
> **Produção AGORA:** `v1.0.14 · commit 081985c · 2026-06-16` (`curl https://scoreodonto.com/api/version`).
> Todo o trabalho de versionamento abaixo marcado 🧪 está no working tree da VPS4 (não commitado).
---
## Mapa rápido (quem é quem)
## 1. O modelo
| Onde | Host | Papel | Socket Docker |
|------|------|-------|----------------|
| VPS4 | `10.99.0.4` | dev + builder (código aqui) | `/var/run/docker.sock` (root) |
| VPS1 | `10.99.0.1` | produção | `unix:///run/user/1000/docker.sock` (rootless) |
| VPS3 | `10.99.0.3` | Postgres + Gitea | — |
> **Push** na `main` produz imagem por **commit** no registry; a **tag `vX.Y.Z`** **promove** essa imagem para produção. **Produção nunca builda — só executa imagens.**
- Repo: `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git` (Gitea).
- Diretório do repo nas duas máquinas: `/home/deploy/stack/scoreodonto.com`.
- Project Compose: `scoreodontocom` (containers `scoreodontocom-*`).
```
PUSH main (commit C) TAG vX.Y.Z (no commit C)
│ │
▼ ▼
CI: build CI: deploy
publica :C, :<versão>, :latest ✅ hoje: REBUILDA + promove + deploya
▼ 🎯 alvo (Passo 5): só re-tag :C→:vX.Y.Z, SEM build
registry ▼
VPS1: pull + up --no-build ✅
APP_VERSION=tag em runtime 🧪 (Passo 3)
```
---
## FASE 0 — Pré-voo (na VPS4)
## 2. Estado por componente (verificado)
| Componente | Status | Detalhe |
|---|---|---|
| Infra VPS1/3/4 + Docker rootless | ✅ | Mapa na §3 |
| Registry (`git.clube67.com/ruicesar/...`) | ✅ | Ver `REGISTRY.md` |
| CI: `act_runner` "vps4-builder" builda+publica em push | ✅ | `.gitea/workflows/build.yml`; runner systemd na VPS4 |
| Deploy por tag (job `deploy` SSH VPS4→VPS1) | ✅ | `deploy-prod.sh` na VPS1 |
| Produção não builda (`image:` + `pull` + `up --no-build`) | ✅ | `docker-compose.prod.yml` |
| Banco DEV isolado em `pgdev`; prod no Postgres da VPS3 | ✅ | Ver `BANCO-DEV-ESTRATEGIA.md` |
| `GET /api/version` responde (de `process.env`) | ✅ | Em prod, valores vêm do **build** da imagem |
| **Versão exibida em Configurações → "Sobre o sistema"** | 🧪 | Passo 1. Em **produção a versão está no Sidebar** |
| **Front/telas consomem `/api/version` (`useAppVersion`); app não usa `APP_VERSION`** | 🧪 | Passos 1/4. Em **prod o front usa `APP_VERSION` do bundle** |
| **Deploy injeta `APP_VERSION`/`APP_ENV` em runtime (`environment`)** | 🧪 | Passo 3 (`compose.prod`/`deploy-prod.sh` no working tree) |
| **Tag promove sem rebuild + validação de integridade** | 🎯 | Passo 5 (§7) |
---
## 3. Mapa de máquinas ✅
| Onde | Host | Papel | Docker |
|---|---|---|---|
| VPS1 | `10.99.0.1` | **Produção** (Traefik + apps) | rootless (`unix:///run/user/1000/docker.sock`) |
| VPS3 | `10.99.0.3` | Postgres (prod) + Gitea + registry | — |
| VPS4 | `10.99.0.4` | **Dev + Builder** (código; runner CI; `pgdev`) | rootless |
- Repo (fonte da verdade): `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git`.
- Project Compose: `scoreodontocom`. Diretório nas duas máquinas: `/home/deploy/stack/scoreodonto.com`.
---
## 4. De onde vem a versão (contrato `/api/version`)
```json
{ "name": "ScoreOdonto API", "version": "v1.0.14", "commit": "081985c",
"build": "2026-06-16 08:06 UTC", "environment": "PROD" }
```
- **commit / build** = carimbados no **build** da imagem (imutáveis — identidade do artefato). ✅
- **version / environment** — **hoje (✅)** também vêm do build da imagem (build arg no CI). **🧪 (Passo 3):** passam a ser injetados no **deploy** em runtime (a partir da tag), liberando a mesma imagem para qualquer tag sem rebuild.
- **Frontend** — **🧪 (Passos 1/4):** lê tudo de `/api/version` via `useAppVersion()`; deixa de embutir versão. **Em produção** ainda embute `APP_VERSION` no bundle.
---
## 5. Runbook — subir um release (fluxo ATUAL ✅)
> ⚠️ **Regra de ouro:** confirme **DEV ou PRODUÇÃO** antes de agir. `dev.scoreodonto.com` = VPS4 (banco `pgdev`, descartável). `scoreodonto.com` = VPS1 (real). **Nunca** `git push --force` na `main`. Push/tag exigem autorização explícita.
```bash
# 1) VPS4: validar em DEV (build local do container de dev)
cd /home/deploy/stack/scoreodonto.com
# 1. Sanidade do backend
node --check backend/server.js
docker compose build scoreodonto-backend scoreodonto-frontend
docker compose up -d --force-recreate scoreodonto-backend scoreodonto-frontend
# conferir em https://dev.scoreodonto.com
# 2. Validar a mudança em DEV (já no ar em https://dev.scoreodonto.com)
# Conferir o bundle servido (deve mudar a cada rebuild):
curl -s https://dev.scoreodonto.com/ | grep -oE 'index-[A-Za-z0-9_-]+\.js' | head -1
```
# 2) ⚠️ transitório (até Passo 5): a TAG precisa casar com frontend/constants.ts
node update-version.js # bump (ex. V1.0.14 → V1.0.15)
```bash
# 3. BACKUP DO BANCO (rede de segurança única — dev/prod compartilham o banco)
# Rodar na VPS3. Usar as credenciais do ambiente/segredo, nunca em texto puro.
ssh deploy@10.99.0.3 'pg_dump -Fc scoreodonto -f /home/deploy/backups/scoreodonto_$(date +%Y%m%d_%H%M).dump'
```
---
## FASE 1 — Versão (na VPS4) ⚠️ passo manual
O bump **não é automático** (`npm run build` é só `vite build`). É preciso incrementar **à mão**:
```bash
cd /home/deploy/stack/scoreodonto.com
node update-version.js # incrementa o patch em frontend/constants.ts (ex.: V1.0.12 → V1.0.13)
grep APP_VERSION frontend/constants.ts
```
> Hoje a versão **não fica visível no navegador** (está no bundle JS). Até a Etapa 3 (versionamento visível), anote a versão que está promovendo.
---
## FASE 2 — Commit & push para o Gitea (na VPS4)
> Só execute com autorização explícita do operador (é o repo de produção).
```bash
cd /home/deploy/stack/scoreodonto.com
git add -A
git commit -m "feat: <descrição> (bump vX.Y.Z)"
# 3) commit + push → CI builda e publica :<commit> + :<versão> + :latest (NÃO deploya)
git add -A && git commit -m "feat: <descrição> (vX.Y.Z)"
git push origin main
# 4) tag = "aprovado p/ produção" → CI (hoje REBUILDA ✅) promove + deploya na VPS1
git tag v1.0.15 && git push origin v1.0.15
# 5) verificar SEM SSH:
curl -s https://scoreodonto.com/api/version # → version/commit/environment
```
> ❗ Push **não** dispara deploy automático hoje (não há listener/webhook ativo). A promoção é a FASE 3.
**Backup do banco de PRODUÇÃO antes de releases sensíveis** (migrações rodam no boot; aditivas/idempotentes):
```bash
ssh deploy@10.99.0.3 'pg_dump -Fc scoreodonto -f ~/backups/scoreodonto_$(date +%Y%m%d_%H%M).dump'
```
> ### ⚠️ Fase transitória — por que `APP_VERSION`/`constants.ts` ainda existem
> Estamos entre o **modelo antigo** (versão escrita à mão em `constants.ts`) e o **novo**
> (identidade pelo **commit**; tags só promovem). Até o **Passo 5**, o CI ainda lê `APP_VERSION`
> para nomear a imagem → o bump manual continua **necessário para evitar colisão de tags no
> registry** (republicar `:vX.Y.Z` com outro código quebraria *"uma tag = um artefato"*).
> **Após o Passo 5:** `constants.ts` e `update-version.js` são removidos, a identidade passa a
> ser o commit, e tags apenas **promovem** artefatos já construídos.
---
## FASE 3 — Promover para produção (na VPS1)
## 6. Rollback ✅
Reverter o **código** é seguro (migrações só adicionam). Por imagem, **sem rebuild**:
```bash
ssh deploy@10.99.0.1
export DOCKER_HOST=unix:///run/user/1000/docker.sock # docker rootless da VPS1
cd /home/deploy/stack/scoreodonto.com
# 1. Trazer o código aprovado
git pull origin main
# 2. Carimbo de versão visível (lido pelos build args do compose) — em PROD use APP_ENV=PROD
export APP_VERSION=$(grep -oE 'V[0-9]+\.[0-9]+\.[0-9]+' frontend/constants.ts | head -1)
export GIT_COMMIT=$(git rev-parse --short HEAD)
export BUILD_TIME=$(date -u +'%Y-%m-%d %H:%M UTC')
export APP_ENV=PROD
# 3. Buildar as imagens (frontend faz vite build; backend npm install)
docker compose build scoreodonto-frontend scoreodonto-backend
# 4. Subir (troca os containers pelas imagens novas)
docker compose up -d scoreodonto-frontend scoreodonto-backend nginx
/home/deploy/stack/scoreodonto.com/deploy-prod.sh v1.0.13 # tag anterior → pull + up --no-build
```
> Os 4 `export` carimbam versão/commit/data/ambiente na imagem. Sem eles, o build ainda funciona mas mostra `dev`/`unknown` no rodapé. Em **DEV** (VPS4) use `APP_ENV=DEV`.
O backend leva ~10–30s no boot (reconecta Postgres/Dragonfly e roda as migrações idempotentes).
Restaurar o dump do banco só em caso extremo (`pg_restore --clean`).
---
## FASE 4 — Verificação pós-deploy (na VPS1)
## 7. Passo 5 — "tag promove, não builda" 🎯
```bash
export DOCKER_HOST=unix:///run/user/1000/docker.sock
Desenho **aprovado (17/jun/2026), não aplicado**. Refina o CI existente para Build Once → Promote → Deploy:
- `build.yml` → 2 jobs por ref: **build** (só push; publica `:<commit>`+`:latest`, sem `APP_VERSION`); **promote** (só tag; re-tag `:<commit>→:vX.Y.Z` via `docker buildx imagetools create`, sem rebuild) → deploy.
- **Validação de integridade antes do deploy:** existe `backend:<C>` e `frontend:<C>`? digests válidos? alias `:vX.Y.Z` == digest de `:<C>`? front e back do **mesmo commit**? Só então deploy (evita deploy parcial).
- Decisões fechadas: manter **`:<commit>`** (sem prefixo); **falhar** se o commit não foi pushado (nunca buildar na tag); **`:latest`** só conveniência.
- Eliminar `update-version.js` + `frontend/constants.ts` (a versão passa a nascer da **tag git**).
- Follow-ups: `GET /api/health`; **política de retenção** do registry.
# Containers no ar
docker ps --format '{{.Names}} | {{.Status}}' | grep score
# Backend: esperar a linha de migração + carimbo de versão
docker logs scoreodontocom-scoreodonto-backend-1 --tail 40 | grep -iE 'migration|VERSION'
# alvo: [MIGRATION] all migrations OK
# [VERSION] ScoreOdonto API vX.Y.Z · commit ... · build ... · PROD
# Confirmar a versão no ar SEM acessar container (a forma definitiva):
curl -s https://scoreodonto.com/api/version
# {"name":"ScoreOdonto API","version":"vX.Y.Z","commit":"...","build":"...","environment":"PROD"}
# E visualmente: a versão aparece no rodapé do menu lateral (Sidebar).
```
**Smoke tests mínimos:** abrir `https://scoreodonto.com`, logar, e exercitar o que mudou (ex.: lançamento financeiro, agenda, salas). Conferir ausência de erro 500 no `docker logs`.
Racional completo em `deploy.md` e na memória `project-cicd-tag-promove-nao-rebuilda`.
---
## FASE 5 — Rollback (se algo quebrar)
As migrações são **aditivas** → reverter o **código** é seguro (colunas/tabelas extras ficam inertes).
```bash
ssh deploy@10.99.0.1
export DOCKER_HOST=unix:///run/user/1000/docker.sock
cd /home/deploy/stack/scoreodonto.com
git log --oneline -5 # achar o commit bom anterior
git checkout <commit-anterior> # ou: git reset --hard <commit-anterior>
docker compose build scoreodonto-frontend scoreodonto-backend
docker compose up -d scoreodonto-frontend scoreodonto-backend
```
> Hoje o rollback **rebuilda** a versão anterior (as imagens são `:latest`, não há tag por versão). Quando a **Etapa 6** entregar deploy por tag + registry, o rollback vira só `docker compose pull` da tag anterior — sem rebuild. Restaurar o dump do banco (FASE 0) só em caso extremo:
> `pg_restore -d "postgresql://scoreodonto_user:<senha>@10.99.0.3:5432/scoreodonto" --clean <arquivo>.dump`
---
## Resumo em uma tela
```
VPS4: validar em dev → node --check → backup do banco (VPS3)
→ node update-version.js → commit → git push origin main (com OK do operador)
VPS1: git pull → docker compose build → docker compose up -d
→ verificar logs ([MIGRATION] all migrations OK) + smoke test
Rollback: git checkout <commit-bom> → build → up -d
```
> **Sequência acordada para fechar o drift:** (1) doc honesta com status ✅/🧪/🎯 [este doc] → (2) commitar Passos 1/3/4 → (3) promover → (4) confirmar `/api/version` → (5) elevar `VERDADE-HOJE.md` a doc principal (com esta convenção e precedência) → (6) Passo 5 → (7) atualizar docs. À medida que cada item 🧪 for promovido, vira ✅ aqui.