Manoel Freitas
7f4ea01f4b
Publish immutable FrankenPHP images to GHCR, auto-deploy staging after CI, and promote the same digest to production with smoke, backup, and rollback docs. Co-authored-by: Cursor <cursoragent@cursor.com>
48 lines
3.9 KiB
Markdown
48 lines
3.9 KiB
Markdown
## Why
|
|
|
|
Fases 0 e 1 estão implementadas e mescladas, mas o critério de saída da Fase 0 (SPEC §18) ainda exige hello-world em staging, e a auditoria de paridade comprovou desvios de fundação: Compose local sem FrankenPHP, `npm audit` e cobertura Domain/Application ausentes dos gates, e-mail verificado e reset de senha incompletos, documentação de PHP divergente e um arquivo PHP próprio sem `strict_types`. Sem fechar esses gaps, a Fase 2 (leads) avançaria sobre uma fundação incompleta frente ao SPEC.
|
|
|
|
## What Changes
|
|
|
|
- Implantar staging na VPS própria via Dokploy (Docker Compose): imagem única por SHA no GHCR, serviços `web`/`queue`/`scheduler`/migrate, PostgreSQL gerenciado, healthcheck `/up`, smoke pós-deploy e rollback por tag SHA anterior.
|
|
- Adicionar workflow GitHub Actions de deploy em `main` após CI verde (build → push GHCR → acionar API Dokploy).
|
|
- Adicionar promoção manual de produção: mesma digest SHA já publicada, alias `:production`, sem rebuild (`workflow_dispatch` + confirmação explícita).
|
|
- Documentar backup PostgreSQL diário (retenção ≥14d), restore e runbook operacional Dokploy/GHCR.
|
|
- Estender `docker-compose.yml` local com serviço de aplicação FrankenPHP (além do PostgreSQL) — **ainda pendente** nesta fatia de deploy.
|
|
- Fixar PHP **8.4** como versão canônica em Docker, CI e documentação — **ainda pendente**.
|
|
- Incluir `npm audit` e cobertura mínima de 80% para `Domain` e `Application` nos gates de qualidade (SPEC §12.6, §13.7, §13.9) — **ainda pendente**.
|
|
- Exigir e-mail verificado no painel Filament e entregar reset de senha seguro (SPEC §12.1; ADM-01) — **ainda pendente**.
|
|
- Corrigir `declare(strict_types=1);` em PHP próprio que ainda falte e cobrir regressões — **ainda pendente**.
|
|
|
|
## Non-Goals
|
|
|
|
Conforme [SPEC.md §4.2](../../SPEC.md):
|
|
|
|
- Deploy automático direto em produção (produção exige promoção humana da mesma imagem).
|
|
- Portal do cliente, multi-tenancy, Redis, FrankenPHP worker mode.
|
|
- Fase 2 (WEB-05 briefing, CRM, E2E-01/E2E-02) — change futura `build-leads-crm` após esta fechar.
|
|
- Provisionamento genérico de VPS/Dokploy para clientes finais.
|
|
- Templates de e-mail de lead, auditoria completa (ADM-02), documentos privados.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
|
|
- `staging-deployment`: deploy automático de staging na VPS via Dokploy com imagem imutável por SHA, processos web/queue/scheduler, migração, healthcheck, smoke e rollback; promoção manual da mesma digest para produção (SPEC §14.3, §15.2, §16.3, §18 Fase 0).
|
|
|
|
### Modified Capabilities
|
|
|
|
- `container-runtime`: Compose local com app FrankenPHP; PHP 8.4 canônico; alinhamento da mesma imagem a processos de staging/produção.
|
|
- `quality-gates`: `npm audit` no gate; cobertura mínima 80% para Domain/Application; job de deploy staging após CI.
|
|
- `health-check`: healthcheck e smoke pós-deploy de staging usam `/up` sem autenticação.
|
|
- `internal-authentication`: e-mail verificado obrigatório para acesso ao painel; reset de senha seguro disponível (SPEC §12.1, ADM-01).
|
|
|
|
## Impact
|
|
|
|
- **Cria (fatia deploy)**: `docker-compose.deploy.yml`, workflows `deploy-staging.yml` / `promote-production.yml`, scripts smoke/Dokploy, docs operacionais Dokploy/GHCR/backup/rollback.
|
|
- **Altera (fatia deploy)**: `bootstrap/app.php` (trusted proxies), `.env.example`, README.
|
|
- **Ainda pendente nesta change**: Compose local FrankenPHP, PHP 8.4 docs, npm audit/coverage, auth verification/reset, strict_types.
|
|
- **Infra (manual)**: projeto Dokploy na VPS (duas stacks), registry GHCR, secrets (`DOKPLOY_*`, DB, `APP_KEY`, Resend/R2), backup S3.
|
|
- **Depende de**: specs já arquivadas (`container-runtime`, `quality-gates`, `health-check`, `internal-authentication`, `transactional-email`, `object-storage`).
|
|
- **Risco**: secrets e registry privados; mitigações: tokens com escopo mínimo, imagem por SHA, healthcheck antes de promover, rollback por tag anterior.
|