diff --git a/doc/DEPLOY-PRODUCAO.md b/doc/DEPLOY-PRODUCAO.md index d8206cd..7fda6f1 100644 --- a/doc/DEPLOY-PRODUCAO.md +++ b/doc/DEPLOY-PRODUCAO.md @@ -1,33 +1,29 @@ # Deploy & Versionamento — Runbook ScoreOdonto -> 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?"*. +> Auditado contra o sistema em **17/jun/2026**. Cada item carrega seu **status real**. > -> **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**. +> **Legenda:** ✅ EM PRODUÇÃO · 🧪 EM DEV (não promovido) · 🎯 ALVO (não implementado). > -> **Produção AGORA:** `v1.0.15 · commit f2eb90c · 2026-06-17` (`curl https://scoreodonto.com/api/version`). -> Os Passos 1/3/4 (versão em runtime) foram **promovidos a produção** em 17/jun (tag `v1.0.15`). +> **Produção AGORA:** `v1.0.16 · commit 471c2c2 · 2026-06-17` (`curl https://scoreodonto.com/api/version`). +> Modelo **Build Once → Promote → Deploy** completo — Passo 5 validado em v1.0.16. Tudo abaixo ✅. --- -## 1. O modelo +## 1. O modelo ✅ -> **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.** +> **Push** na `main` builda **uma vez** e publica por **commit**; a **tag `vX.Y.Z`** **re-tagueia** esse mesmo artefato (sem rebuild) e deploya. **Produção nunca builda — só executa imagens.** ``` PUSH main (commit C) TAG vX.Y.Z (no commit C) │ │ ▼ ▼ - CI: build CI: deploy - publica :C, :, :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, em prod) + CI: build (1x) CI: promote (SEM build) ✅ + publica :C + :latest re-tag :C → :vX.Y.Z (MESMO digest) + deploy + ▼ ▼ + registry VPS1: pull :vX.Y.Z + up --no-build + APP_VERSION=tag injetada em runtime ``` +Prova (v1.0.16): `:v1.0.16` tem **digest idêntico** a `:471c2c2` — a tag é só um rótulo sobre a imagem já testada. --- @@ -37,15 +33,14 @@ |---|---|---| | 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 | +| CI: job `build` publica por **commit** em push (sem `APP_VERSION`) | ✅ | `.gitea/workflows/build.yml` (runner `vps4-builder`) | +| Job `promote` por tag: re-tag `:→:vX.Y.Z` (sem rebuild) + deploy | ✅ | validado em v1.0.16 (`:v1.0.16` == `:471c2c2`) | +| Validação de integridade no promote (commit existe? digest igual? front+back mesmo commit) | ✅ | falha se o commit não foi pushado | | 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`) | ✅ | No ar: v1.0.15 · f2eb90c · PROD | -| **Versão exibida em Configurações → "Sobre o sistema"** | ✅ | Passo 1 (promovido em v1.0.15; saiu do Sidebar) | -| **Front/telas consomem `/api/version` (`useAppVersion`); app não usa `APP_VERSION`** | ✅ | Passos 1/4 (em prod desde v1.0.15) | -| **Deploy injeta `APP_VERSION`/`APP_ENV` em runtime (`environment`)** | ✅ | Passo 3 (`compose.prod`/`deploy-prod.sh` em prod) | -| **Tag promove sem rebuild + validação de integridade** | 🎯 | Passo 5 (§7) — único item pendente | +| Versão em runtime (`/api/version`) → Configurações + telas públicas | ✅ | `useAppVersion()`; sem `APP_VERSION` manual | +| `APP_VERSION`/`APP_ENV` injetados no deploy em runtime | ✅ | `compose.prod` `environment` | +| Versão **nasce da tag git** (`constants.ts`/`update-version.js` removidos) | ✅ | Passo 5 | --- @@ -53,90 +48,70 @@ | Onde | Host | Papel | Docker | |---|---|---|---| -| VPS1 | `10.99.0.1` | **Produção** (Traefik + apps) | rootless (`unix:///run/user/1000/docker.sock`) | +| VPS1 | `10.99.0.1` | **Produção** (Traefik + apps) | rootless | | 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`. +- Repo: `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git`. Project Compose: `scoreodontocom`. --- -## 4. De onde vem a versão (contrato `/api/version`) +## 4. De onde vem a versão (`/api/version`) ```json -{ "name": "ScoreOdonto API", "version": "v1.0.15", "commit": "f2eb90c", - "build": "2026-06-17 03:37 UTC", "environment": "PROD" } +{ "name": "ScoreOdonto API", "version": "v1.0.16", "commit": "471c2c2", + "build": "2026-06-17 10:35 UTC", "environment": "PROD" } ``` -- **commit / build** = carimbados no **build** da imagem (imutáveis — identidade do artefato). ✅ -- **version / environment** = **injetados no deploy em runtime** (a partir da tag) via `environment` do `compose.prod` ✅ (Passo 3, em prod) — a mesma imagem pode ser promovida sob qualquer tag sem rebuild. -- **Frontend** = lê tudo de `/api/version` via `useAppVersion()`; **não embute mais a versão** ✅ (Passos 1/4, em prod). Fonte única = backend. +- **commit / build** = carimbados no **build** (imutáveis — identidade do artefato). +- **version / environment** = **injetados no deploy em runtime** (a partir da tag). A mesma imagem é promovida sob qualquer tag, sem rebuild. +- **Frontend** lê tudo de `/api/version` (`useAppVersion()`); não embute versão. Fonte única = backend. --- -## 5. Runbook — subir um release (fluxo ATUAL ✅) +## 5. Runbook — subir um release ✅ -> ⚠️ **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. +> ⚠️ **Regra de ouro:** confirme **DEV ou PRODUÇÃO**. `dev.scoreodonto.com` = VPS4 (banco `pgdev`). `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) +# 1) VPS4: validar em DEV cd /home/deploy/stack/scoreodonto.com 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 +docker compose up -d --force-recreate scoreodonto-backend scoreodonto-frontend # https://dev.scoreodonto.com -# 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) - -# 3) commit + push → CI builda e publica : + : + :latest (NÃO deploya) -git add -A && git commit -m "feat: (vX.Y.Z)" +# 2) commit + push → CI builda 1x e publica : + :latest (NÃO deploya) +git add -A && git commit -m "feat: " 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 +# 3) tag = "aprovado p/ produção" → job PROMOTE re-tagueia :→:vX.Y.Z (SEM rebuild) + deploya +# (o número da versão é livre — não precisa casar com nenhum arquivo) +git tag -a vX.Y.Z -m "release vX.Y.Z" && git push origin vX.Y.Z -# 5) verificar SEM SSH: -curl -s https://scoreodonto.com/api/version # → version/commit/environment +# 4) verificar (sem SSH) +curl -s https://scoreodonto.com/api/version # → vX.Y.Z · · PROD ``` -**Backup do banco de PRODUÇÃO antes de releases sensíveis** (migrações rodam no boot; aditivas/idempotentes): +**Backup do banco de PRODUÇÃO antes de releases sensíveis** (via container, pois não há shell na VPS3): ```bash -ssh deploy@10.99.0.3 'pg_dump -Fc scoreodonto -f ~/backups/scoreodonto_$(date +%Y%m%d_%H%M).dump' +docker run --rm -e PGPASSWORD= -v /home/deploy/backups:/b postgres:18 \ + pg_dump -h 10.99.0.3 -U scoreodonto_user -d scoreodonto -Fc -f /b/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. - --- ## 6. Rollback ✅ -Reverter o **código** é seguro (migrações só adicionam). Por imagem, **sem rebuild**: +Por imagem, **sem rebuild** — na VPS1: ```bash -ssh deploy@10.99.0.1 -/home/deploy/stack/scoreodonto.com/deploy-prod.sh v1.0.13 # tag anterior → pull + up --no-build +/home/deploy/stack/scoreodonto.com/deploy-prod.sh # pull + up --no-build ``` -Restaurar o dump do banco só em caso extremo (`pg_restore --clean`). +⚠️ A referência confiável é o **commit** (`:`). Tags `:vX.Y.Z` antigas (pré-Passo 5) podem ter sido republicadas com código diferente — a partir do Passo 5, `:vX.Y.Z` é sempre um alias imutável do commit. Migrações são aditivas (voltar o código é seguro). Dump em `/home/deploy/backups/` só em extremo. --- -## 7. Passo 5 — "tag promove, não builda" 🎯 +## 7. Follow-ups (não bloqueiam) 🎯 +- `GET /api/health` (monitoramento/diagnóstico). +- **Política de retenção** do registry (uma imagem `:` por push acumula). +- Reconciliar o repo na VPS1 (working tree sujo, não afeta o deploy por imagem). -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 `:`+`:latest`, sem `APP_VERSION`); **promote** (só tag; re-tag `:→:vX.Y.Z` via `docker buildx imagetools create`, sem rebuild) → deploy. -- **Validação de integridade antes do deploy:** existe `backend:` e `frontend:`? digests válidos? alias `:vX.Y.Z` == digest de `:`? front e back do **mesmo commit**? Só então deploy (evita deploy parcial). -- Decisões fechadas: manter **`:`** (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. - -Racional completo em `deploy.md` e na memória `project-cicd-tag-promove-nao-rebuilda`. - ---- - -> **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. +Racional do modelo em `deploy.md`; histórico em `project-cicd-tag-promove-nao-rebuilda` (memória). diff --git a/doc/VERDADE-HOJE.md b/doc/VERDADE-HOJE.md index d858b9c..0146c0d 100644 --- a/doc/VERDADE-HOJE.md +++ b/doc/VERDADE-HOJE.md @@ -9,8 +9,8 @@ ### 1. Onde está o código? - **Fonte da verdade:** Gitea na **VPS3**, repo `ruicesar/scoreodonto.com`. - **Dev (trabalho):** VPS4 em `/home/deploy/stack/scoreodonto.com`. -- **Produção:** VPS1 roda **imagens versionadas do registry** (não código-fonte). No ar: **v1.0.15 · commit `f2eb90c`**. -- **Documentação:** centralizada em `scoreodonto.com/documentação/`. +- **Produção:** VPS1 roda **imagens versionadas do registry** (não código-fonte). No ar: **v1.0.16 · commit `471c2c2`**. +- **Documentação:** centralizada em `scoreodonto.com/doc/` (pasta única). ### 2. Onde está o banco? - **Produção:** PostgreSQL no host da **VPS3** (`10.99.0.3:5432`), banco `scoreodonto`, user `scoreodonto_user`. @@ -25,12 +25,12 @@ ### 4. Quem faz deploy? - **CI/CD por tag (Gitea Actions).** Push na `main` → o runner `act_runner` "vps4-builder" (VPS4, rootless) builda e **publica no registry** (NÃO deploya). `git tag vX.Y.Z && git push` → CI + job `deploy` promove para a VPS1 (`deploy-prod.sh`). - **Produção consome imagem** (`pull` + `up -d --no-build`). -- ⚠️ Hoje a **tag rebuilda** antes de promover; o **Passo 5** mudará para a tag apenas **re-taguear** o artefato já construído por commit. +- ✅ **Build Once → Promote (Passo 5, validado em produção):** push builda 1× e publica por **commit** (`:`); a **tag re-tagueia** esse artefato como `:vX.Y.Z` (sem rebuild — digest idêntico) e deploya. Provado em v1.0.16 (`:v1.0.16` == `:471c2c2`, mesmo digest). ### 5. Como versiona? -- A versão exibida vem do **backend em runtime**: `GET /api/version` (de `process.env`), mostrada em **Configurações → "Sobre o sistema"** e nas telas públicas (o frontend consome via `useAppVersion()`, não embute mais a versão). No ar: **v1.0.15 · `f2eb90c` · PROD**. -- No deploy, `APP_VERSION` (= tag) e `APP_ENV=PROD` são **injetados em runtime**; `commit`/`build` vêm carimbados na imagem. -- ⚠️ **Legado transitório:** `frontend/constants.ts` (`APP_VERSION`) + `update-version.js` ainda existem **só** para o CI nomear a imagem (bump manual evita colisão de tag). Serão **eliminados no Passo 5** (a versão nascerá da tag git). +- A versão exibida vem do **backend em runtime**: `GET /api/version` (de `process.env`), mostrada em **Configurações → "Sobre o sistema"** e nas telas públicas (o frontend consome via `useAppVersion()`, não embute mais a versão). No ar: **v1.0.16 · `471c2c2` · PROD**. +- A versão **nasce da tag git** e é **injetada no deploy em runtime** (`APP_VERSION`=tag, `APP_ENV=PROD`); `commit`/`build` vêm carimbados na imagem. +- ✅ **`constants.ts`/`update-version.js` foram removidos** (Passo 5) — não há mais versão manual. ### 6. Como volta uma versão (rollback)? - **Por imagem, sem rebuild:** na VPS1, `./deploy-prod.sh ` → `pull` + `up -d --no-build`. @@ -39,4 +39,4 @@ --- ## Veredito de uma linha -> O código vive no Gitea (VPS3); a **produção (VPS1) roda imagens versionadas do registry** (hoje **v1.0.15**), sem buildar; o **DEV está isolado no `pgdev`** (não toca o banco de produção). **CI/CD por tag ativo**, com **versão visível em runtime** (`/api/version` → Configurações). Pendência técnica principal: **Passo 5** (tag promove sem rebuild; eliminar o `APP_VERSION` manual). +> O código vive no Gitea (VPS3); a **produção (VPS1) roda imagens versionadas do registry** (hoje **v1.0.16**), sem buildar; o **DEV está isolado no `pgdev`** (não toca o banco de produção). **CI/CD por tag ativo** no modelo **Build Once → Promote → Deploy** (push builda por commit; tag re-tagueia sem rebuild e deploya — validado em v1.0.16), com **versão visível em runtime** (`/api/version` → Configurações) nascendo da tag git.