docs: registry de imagens (Etapa 4) — Gitea Container Registry

- REGISTRY.md: login, convenção de nomes, build+push, pull/rollback, gotcha do 499 - arquitetura.md/deploy.md: registry agora ativo (git.clube67.com), não mais 'não existe' Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-16 08:30:05 +02:00
parent adf96002b6
commit 89f998964f
3 changed files with 92 additions and 3 deletions
@@ -0,0 +1,89 @@
+# Registry de imagens — Container Registry do Gitea
+
+> **Estado: ATIVO e validado** (16/jun/2026, Etapa 4). Não há serviço novo a manter: usamos o **Container Registry embutido do Gitea** (v1.26.1) na VPS3.
+
+---
+
+## 1. O que é
+
+O Gitea já expõe um **registry OCI/Docker** nativo. Não foi preciso instalar `registry:2` nem tocar em `daemon.json`/`insecure-registries`. As imagens do ScoreOdonto ficam versionadas junto do código, no mesmo Gitea que é a fonte da verdade.
+
+| Item | Valor |
+|------|-------|
+| Endereço (push/pull) | **`git.clube67.com`** (HTTPS, TLS válido via Traefik) |
+| Namespace | `ruicesar/` (dono do repo no Gitea) |
+| Alternativa interna | `10.99.0.3:3000` — **NÃO usar**: HTTP exige `insecure-registries` + restart do Docker (derruba produção) |
+| Auth | usuário Gitea + **token** com escopo `write:package` / `read:package` |
+
+> Usamos sempre o domínio **HTTPS** justamente para **não** precisar reconfigurar nem reiniciar o Docker em VPS4/VPS1 (Live Restore está desligado → restart bouncearia todos os containers).
+
+---
+
+## 2. Login (uma vez por máquina)
+
+Em cada máquina que vai dar push/pull (VPS4 builda; VPS1 consome):
+
+```bash
+docker login git.clube67.com -u <usuario_gitea>
+# senha = TOKEN do Gitea (Configurações → Aplicações → Gerar Token, escopos write:package + read:package)
+```
+
+A credencial fica no keystore do Docker (`~/.docker/config.json`). **Nunca** colocar token em código, doc, script ou log. Se um token vazar (ex.: colado em chat), **revogue no Gitea** e gere outro.
+
+---
+
+## 3. Convenção de nomes
+
+```
+git.clube67.com/ruicesar/scoreodonto-backend:<versão>
+git.clube67.com/ruicesar/scoreodonto-frontend:<versão>
+```
+
+- `<versão>` = semver com o mesmo valor de `APP_VERSION` (ex.: `v1.0.13`).
+- Mantém-se também a tag móvel `:latest` apontando para a última.
+- A tag semântica é o que a **Etapa 6 (deploy por tag)** usa para promover à produção.
+
+---
+
+## 4. Build + push (fluxo manual de hoje, na VPS4)
+
+```bash
+cd /home/deploy/stack/scoreodonto.com
+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          # ou DEV para imagens de teste
+
+docker compose build scoreodonto-backend scoreodonto-frontend
+
+V=$(echo "$APP_VERSION" | tr 'V' 'v')   # V1.0.13 -> v1.0.13
+docker tag scoreodontocom-scoreodonto-backend:latest  git.clube67.com/ruicesar/scoreodonto-backend:$V
+docker tag scoreodontocom-scoreodonto-frontend:latest git.clube67.com/ruicesar/scoreodonto-frontend:$V
+docker push git.clube67.com/ruicesar/scoreodonto-backend:$V
+docker push git.clube67.com/ruicesar/scoreodonto-frontend:$V
+```
+
+> ⚠️ **HTTP 499 em camada grande = timeout transitório do proxy.** O push é resumível: basta **repetir o `docker push`** que as camadas já enviadas são puladas e a faltante completa. (Visto e contornado na validação inicial.)
+
+---
+
+## 5. Pull (na VPS1, quando a Etapa 6 estiver pronta)
+
+```bash
+export DOCKER_HOST=unix:///run/user/1000/docker.sock
+docker pull git.clube67.com/ruicesar/scoreodonto-backend:v1.0.13
+docker pull git.clube67.com/ruicesar/scoreodonto-frontend:v1.0.13
+# depois: compose apontando para essas imagens + docker compose up -d
+```
+
+Rollback = `docker pull` da tag anterior + `up -d`. Sem rebuild.
+
+---
+
+## 6. Validação feita (16/jun/2026)
+
+- `docker login git.clube67.com` (usuário `ruicesar`) → **Login Succeeded**.
+- Push de `scoreodonto-backend:v1.0.13`/`:latest` e `scoreodonto-frontend:v1.0.13`/`:latest` → OK (com 1 retry por 499 transitório).
+- Teste de pull (remover tag local + `docker pull`) → **Downloaded** OK.
+
+Próximos: **Etapa 5** (automatizar build+push no Gitea Actions) e **Etapa 6** (deploy por tag na VPS1 consumindo este registry).