Pular para conteúdo

Tirar o site de documentação de produção, servir do dev-remote

Motivação

O site de docs.garantora.com.br vivia em infra/prd desde a migração de 2026-08-30, e cada atualização de Markdown só ficava visível depois de um deploy de produção — não é esse o objetivo de um site de documentação em desenvolvimento ativo.

Comportamento atual

Antes deste ajuste: o serviço docs (build MkDocs + nginx) e o site-block do Caddy para docs.garantora.com.br viviam em infra/prd, subindo junto com o /ship.

Comportamento desejado

O serviço docs e o site-block do Caddy passam a viver em infra/dev-remote. Atualizar a documentação passa a ser /devremote-rebuild docs, o mesmo mecanismo já usado para apps/api e apps/web. Produção não serve mais docs.garantora.com.br em nenhuma forma.

Escopo

  • infra/prd: removidos o serviço docs, o site-block do Caddy e as variáveis DOCS_DOMAIN/DOCS_BASIC_AUTH_*.
  • infra/dev-remote: adicionados o serviço docs e as mesmas variáveis, reaproveitando a credencial de Basic Auth que já protegia o site em produção. Dois Caddyfiles ganharam bloco para docs.garantora.com.br: o Caddyfile (modo standalone) e o Caddyfile.behind-edge — este último é o que está de fato em uso nesta VPS (ela roda co-hospedada com outra stack; ver infra/dev-remote/README.md, "Co-hospedado"). A primeira versão deste tweak só tinha mexido no standalone, por engano — corrigido antes do push, com o usuário apontando o gap.
  • infra/dev-remote/README.md: passo a passo do server do nginx do host que docs.garantora.com.br precisa, ao lado do exemplo já existente de dev.garantora.com.br.
  • infra/prd/docs.Dockerfile e infra/prd/docs-nginx.conf movidos para infra/dev-remote/.
  • docs/operations/documentation-platform.md: arquitetura, deploy e rollback reescritos para o novo dono do serviço, incluindo o hop pelo nginx do host que o modo co-hospedado exige.
  • .claude/skills/devremote-rebuild/SKILL.md: a tabela de decisão não sabia que docs/ precisa de rebuild (mapeava para "nada"); agora mapeia para o serviço docs.

Fora do escopo

  • Backfill ou redirecionamento da URL antiga: produção simplesmente para de responder em docs.garantora.com.br assim que o DNS mudar de alvo.

Impactos

Mudança de infraestrutura, sem código de produto tocado — não mexe em permissão, isolamento, migration nem contrato de API. Depende de duas ações fora deste repositório, na VPS e no provedor de DNS — ver Validação.

Critérios de aceite

Sem comportamento testável por suíte automatizada — é configuração de infraestrutura. A verificação é operacional (ver Validação).

Validação

  • make preflight: limpo (arquivos alterados não tocam apps/web nem apps/api).
  • python3 scripts/docs_lint.py: ok — 83 documentos com front matter válido, catálogo consistente.
  • mkdocs build --strict não foi rodado localmente (sem mkdocs instalado neste host); a mudança em documentation-platform.md foi só de prosa, sem novo link nem alteração de nav.
  • Pendente, fora deste repositório, nesta ordem:
  • /devremote-rebuild docs — sobe o serviço docs e recria o garantora-caddy com o bloco novo, na VPS do dev-remote.
  • Um server novo no nginx do host da VPS para docs.garantora.com.br → 127.0.0.1:8180 + certificado via certbot (passo a passo em infra/dev-remote/README.md).
  • Apontar o A record de docs.garantora.com.br para 145.223.94.55 (dev-remote) em vez de 179.198.118.166 (produção) — mudança de DNS externa.

A ordem importa: só depois dos três, o domínio responde de algum lugar. Até lá, e antes de qualquer deploy de produção que remova o serviço de lá, produção continua sendo a única a responder por docs.garantora.com.br — tirar o serviço de produção sem os três passos acima prontos deixaria o domínio sem backend nenhum.

Documentos relacionados