VPS 4 Builder
0f50835114
- VERDADE-HOJE.md: reescrito p/ a verdade de 17/jun — banco DEV isolado (pgdev, não compartilha mais), produção roda imagem v1.0.15, versão em runtime via /api/version. Declarado documento principal (prevalece em divergência). - deploy.md: §5 rollback ✅ (existe); §6 corrigida — remove o "não há CI/registry/deploy" (era falso/contraditório); CI/CD por tag ATIVO, falta só o Passo 5. - DEPLOY-PRODUCAO.md: status 🧪→✅ dos Passos 1/3/4 (promovidos em v1.0.15). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
103 lines
6.4 KiB
Markdown
103 lines
6.4 KiB
Markdown
# Deploy ScoreOdonto — Como um commit vira produção (estado-ALVO)
|
||
|
||
> Este documento responde **uma** pergunta: **"como um commit vira produção?"**
|
||
> Descreve o **fluxo-alvo** com **Gitea como motor de CI/CD**. O que já existe hoje está marcado como ✅; o que ainda será construído está marcado como 🔜.
|
||
> Para a realidade da infra ver `arquitetura.md`. Para o procedimento manual executável **hoje** ver `DEPLOY-PRODUCAO.md`.
|
||
|
||
---
|
||
|
||
## 1. Princípios (inegociáveis)
|
||
|
||
1. **Gitea (VPS3) é a fonte única da verdade** e o motor de CI/CD.
|
||
2. **Produção (VPS1) nunca builda e nunca recebe código-fonte** — só consome **imagens versionadas** prontas.
|
||
3. **Build acontece fora da produção** (na CI / na VPS4).
|
||
4. **Deploy é um ato deliberado por TAG**, nunca automático em todo push (a `main` é usada para desenvolvimento e o banco é compartilhado — promover sem querer é perigoso).
|
||
5. **Rollback é trocar a imagem** por uma tag anterior — sem rebuild, sem recompilar, sem copiar arquivo.
|
||
6. **Toda imagem é rastreável**: carrega versão semântica + commit + data de build.
|
||
|
||
---
|
||
|
||
## 2. O fluxo-alvo, em uma frase
|
||
|
||
> **Push** abastece o desenvolvimento e (🔜) **produz uma imagem versionada no registry**;
|
||
> **criar uma tag `vX.Y.Z`** é o que **promove** essa imagem para produção.
|
||
|
||
```
|
||
git push ──► Gitea (VPS3) ──► CI: build da imagem ──► Registry privado (VPS3)
|
||
(na main) (versão+commit+data) imagem :vX.Y.Z
|
||
│
|
||
criar tag vX.Y.Z ────┘
|
||
▼
|
||
VPS1: docker compose pull + up -d
|
||
(troca o container pela imagem da tag)
|
||
▼
|
||
Produção rodando vX.Y.Z
|
||
```
|
||
|
||
---
|
||
|
||
## 3. As duas metades do fluxo
|
||
|
||
### Metade A — Integração contínua (push → imagem) ✅ FEITO
|
||
1. Desenvolvedor trabalha na VPS4 e valida em `https://dev.scoreodonto.com`.
|
||
2. `git push origin main` (ou tag `v*`) para o Gitea (VPS3).
|
||
3. A **CI do Gitea** (Gitea Actions) builda backend+frontend via `docker compose build`, injetando **versão, commit curto e data de build** (build args → `VITE_*`/`process.env`).
|
||
4. As imagens são enviadas ao **Container Registry do Gitea** com tags `:<versão>`, `:<commit-curto>` e `:latest`.
|
||
5. **Nada vai para produção aqui.** Esta metade só produz e guarda o artefato.
|
||
|
||
> **Implementado em 16/jun/2026.** Workflow: `.gitea/workflows/build.yml`. Runner: `vps4-builder` (act_runner 0.6.1, **modo host** com Docker, serviço systemd `act_runner` na VPS4, label `self-hosted`). Login no registry usa o secret `REGISTRY_TOKEN` se presente, senão a credencial do host. Validado: push na main → build → `scoreodonto-{backend,frontend}:v1.0.13`/`:<commit>`/`:latest` publicados.
|
||
|
||
### Metade B — Entrega por tag (tag → produção) ✅ FEITO
|
||
1. Quando uma versão está aprovada, cria-se uma **tag semântica**: `git tag v1.0.15 && git push origin v1.0.15`.
|
||
2. A CI builda e publica a imagem `:v1.0.15` no registry **e** o job `deploy` (só em tags `v*`) promove para a VPS1.
|
||
3. Na VPS1, o `deploy-prod.sh <tag>` faz `docker compose pull` + `up -d --no-build` apontando para a imagem da tag.
|
||
4. A versão visível (rodapé/endpoint `/api/version`) confirma a tag no ar com `environment: PROD`.
|
||
|
||
> **Implementado em 16/jun/2026.** `docker-compose.prod.yml` (imagens do registry, sem build) + `deploy-prod.sh <tag>` (na VPS1) + job `deploy` no workflow (SSH VPS4→VPS1, só em tags). **Push na main NÃO deploya — só tags.** Rollback: `deploy-prod.sh <tag-anterior>`. Validado: v1.0.13 promovida e confirmada (`V1.0.13 · fc0d65f · PROD`).
|
||
|
||
---
|
||
|
||
## 4. Versionamento visível (pré-requisito da confiança) ✅ FEITO
|
||
|
||
> Implementado em 16/jun/2026 (Etapa 3). O build carimba versão/commit/data/ambiente via build args (`GIT_COMMIT`, `BUILD_TIME`, `APP_ENV`, `APP_VERSION`) → `import.meta.env.VITE_*` no frontend e `process.env` no backend. Visível no **rodapé do Sidebar**, no endpoint **`GET /api/version`** e na **linha de boot** `[VERSION] …` dos logs.
|
||
|
||
Cada build carimba e **exibe**:
|
||
|
||
```
|
||
ScoreOdonto
|
||
v1.0.15
|
||
commit: 7a9b3c1
|
||
build: 2026-06-16 14:32 UTC
|
||
ambiente: PRODUÇÃO
|
||
```
|
||
|
||
Visível no **rodapé** da aplicação, em um **endpoint de diagnóstico** (ex.: `GET /api/version`) e na **linha de boot** dos logs. Hoje a versão fica escondida no bundle `index-<hash>.js` (ver `arquitetura.md` §7) — esta é a primeira melhoria de maior valor.
|
||
|
||
---
|
||
|
||
## 5. Rollback ✅
|
||
|
||
- Por imagem, **sem rebuild**: na VPS1, `./deploy-prod.sh <tag-ou-commit-anterior>` → `pull` + `up -d --no-build`.
|
||
- ⚠️ Use uma referência que corresponda ao que estava no ar: a tag `:vX.Y.Z` pode ter sido **republicada** com outro código (colisão de tags pré-Passo 5) — o **commit** (`:<sha>`) é a referência confiável. O banco é aditivo (voltar o código é seguro); restaurar dump só em caso extremo.
|
||
|
||
---
|
||
|
||
## 6. Estado de hoje (corrente) ✅
|
||
|
||
**O CI/CD por tag está ATIVO** (Etapas 3–6 concluídas, ver §7): push na `main` builda e publica no registry; tag `vX.Y.Z` promove para a VPS1. Produção **não builda** — consome a imagem do registry. Para o estado atual factual ver **`VERDADE-HOJE.md`**; para operar ver **`DEPLOY-PRODUCAO.md`**.
|
||
|
||
O que **ainda falta** (o alvo deste documento) é o **Passo 5**: hoje a **tag rebuilda** antes de promover; o alvo é a tag apenas **re-taguear** o artefato já construído por commit (*Build Once → Promote*), eliminando `constants.ts`/`APP_VERSION` manual.
|
||
|
||
---
|
||
|
||
## 7. Roadmap para sair do "hoje" e chegar no "alvo"
|
||
|
||
| Etapa | Entrega | Status |
|
||
|-------|---------|--------|
|
||
| 3 | Versionamento visível (rodapé + endpoint + log) | ✅ |
|
||
| 4 | Registry Docker privado na VPS3 | ✅ (Gitea Container Registry — ver `REGISTRY.md`) |
|
||
| 5 | Pipeline de build no Gitea (push → imagem → registry), **sem deploy** | ✅ (`.gitea/workflows/build.yml` + runner `vps4-builder`) |
|
||
| 6 | Deploy por TAG (`vX.Y.Z` → produção na VPS1) + rollback por imagem | ✅ (`deploy-prod.sh` + job `deploy` em tags) |
|
||
|
||
Quando as Etapas 3–6 estiverem prontas, este documento deixa de ter marcações 🔜 e passa a descrever o fluxo corrente.
|