Deployment Guide | Ponta a Ponta

governanca publicacao infra

Passo a passo para ir do zero às 3 wikis no ar. Tempo estimado: ~4h de trabalho efetivo do Pedro (ou do devops Anouk). Fases podem ser feitas em dias diferentes. Repo de destino: Anouk-Partners/colliers-costal-wiki

Fase 0 — pré-requisitos

Conta GitHub Anouk ativa (org Anouk-Partners)
Repo Anouk-Partners/colliers-costal-wiki criado
Conta Cloudflare ativa com domínio anoukpartners.com gerenciado lá (ou zona delegada)
Google Workspace Anouk configurado (para SSO)
Node ≥ 22 instalado localmente (Quartz 4.5+ exige)
git, rclone instalados
Este repo atual (vault) aberto no Obsidian

Fase 1 — popular repo Quartz (~30 min)

O repo Anouk-Partners/colliers-costal-wiki já existe (vazio ou com README default). O plano: clonar local, puxar Quartz v4 como base, mergear o scaffold desta pasta, commitar.

1.1 Clonar o repo

cd ~/workspace   # ou onde preferir
git clone https://github.com/Anouk-Partners/colliers-costal-wiki.git
cd colliers-costal-wiki

1.2 Trazer código Quartz v4 como base

Opção A — subtree (recomendado, permite merge de updates Quartz no futuro):

git remote add upstream-quartz https://github.com/jackyzha0/quartz.git
git fetch upstream-quartz
git merge upstream-quartz/v4 --allow-unrelated-histories -m "chore: import Quartz v4 upstream"

Opção B — cópia simples (mais fácil, sem histórico upstream):

cd /tmp
git clone --branch v4 --depth 1 https://github.com/jackyzha0/quartz.git quartz-base
rsync -av --exclude='.git' quartz-base/ ~/workspace/colliers-costal-wiki/
cd ~/workspace/colliers-costal-wiki
git add .
git commit -m "chore: Quartz v4 base"

1.3 Instalar deps

npm ci
# se npm ci falhar porque não há lockfile, usar:
# npm install

1.4 Mergear scaffold deste vault

Do vault (Obsidian) para o repo Quartz, copiar:

Origem (vault)	Destino (repo)
`99-operacao/publish/quartz/quartz.config.ts`	`quartz.config.ts` (sobrescrever Quartz default)
`99-operacao/publish/quartz/quartz.layout.ts`	`quartz.layout.ts` (sobrescrever Quartz default — Explorer customizado)
`99-operacao/publish/quartz/filters/audience-filter.ts`	`quartz/plugins/filters/audience-filter.ts`
`99-operacao/publish/quartz/filters/ignore-patterns.ts`	`quartz/plugins/filters/ignore-patterns.ts`
`99-operacao/publish/quartz/util/path.ts`	`quartz/util/path.ts` (patch: wikilinks `[[hunter]]` resolvem para pasta `hunter/_index` no estilo Obsidian)
`99-operacao/publish/workflows/wiki.yml`	`.github/workflows/wiki.yml`

Nota: Quartz v4 não aceita --config; usa sempre ./quartz.config.ts. A audiência é controlada via env var AUDIENCE.

Adicionar em quartz/plugins/filters/index.ts (após os exports existentes):

export { AudienceFilter } from "./audience-filter"
export { IgnorePatterns } from "./ignore-patterns"

1.5 Primeiro build local (sanity check)

Copiar o vault para content/ (one-off manual):

mkdir -p content
rsync -av --exclude='.obsidian' --exclude='_bases' --exclude='_templates' \
  --exclude='99-operacao/publish' --exclude='99-operacao/scripts' \
  --exclude='agentes-core/axios/memory' \
  "/Users/ppvilla/Library/CloudStorage/GoogleDrive-pedro.villa@anoukpartners.com/Meu Drive/Colliers_Projeto/" content/

Build (env var controla audiência; sem --config):

AUDIENCE=internal BASE_URL=interno.colliers.wiki.anoukpartners.com npx quartz build --output public-internal
AUDIENCE=client   BASE_URL=cliente.colliers.wiki.anoukpartners.com npx quartz build --output public-client
AUDIENCE=board    BASE_URL=board.colliers.wiki.anoukpartners.com   npx quartz build --output public-board

Servir:

npx quartz build --serve --output public-internal
# abrir http://localhost:8080

Validar: arquivos bloqueados (memory, feedback, scripts) não aparecem. Audience filter funcionando.

1.6 Commit e push

git add .
git commit -m "feat: scaffold Quartz + audience filter (3 audiences)"
git push origin main

Se a política do repo exigir PR: criar branch e PR; caso contrário, push direto no main é suficiente.

Fase 2 — Cloudflare Pages + Access (~1.5h)

Seguir cloudflare-setup seção por seção:

Criar 3 projetos Cloudflare Pages
Criar API token + Account ID secrets no GitHub
Configurar custom domains (ou usar .pages.dev inicialmente)
Configurar Google Workspace como Identity Provider no Access
Criar 3 Access Applications com políticas distintas
Criar grupos lista-costal e lista-board em Access → Groups
Testar login nas 3 wikis com e-mails distintos

Fase 3 — sync vault → repo (~30 min)

Seguir sync-options opção A (rclone):

brew install rclone local
rclone config — novo remote “gdrive”
Testar: rclone sync "gdrive:Colliers_Projeto" ./content-test --dry-run
cat ~/.config/rclone/rclone.conf → copiar
Adicionar secret VAULT_REMOTE_CONFIG no repo GitHub
Disparar workflow manualmente: Actions → Build e deploy das wikis → Run workflow
Verificar content/ populado após sync
Verificar 3 deploys Cloudflare Pages OK

Fase 4 — tagagem inicial do vault (~1h)

Antes de abrir a wiki ao cliente ou board, tagar os arquivos-chave:

Seguir checklist em publish-contract §4. Lista mínima:

HOME.md → publish: [internal, client, board]
README.md → publish: [internal, client, board]
02-costal/costal-plano.md (folder note) → publish: [internal, client]
02-costal/plano/2026-04-17_geral.md → publish: [internal, client]
05-arquitetura-empresarial/arquitetura-empresarial.md → publish: [internal, client]
05-arquitetura-empresarial/modelo-global-dados.md → publish: [internal, client]
00-projeto/governanca/visao-geral.md → publish: [internal, client]
Criar 00-projeto/board/brief-board-2026-q2.md dedicado → publish: [internal, client, board]

Re-sync depois da tagagem: disparar workflow manualmente.

Fase 5 — validação e entrega (~30 min)

5.1 Checklist final

5.2 Entrega formal

Registrar decisão em decisoes: “Wiki do projeto publicada — 3 audiências”
Comunicar a Igor o URL da wiki cliente
Preparar brief executivo com URL para board (quando houver conteúdo de board)
Atualizar HOME com links das wikis (só no vault — as wikis não linkam para elas mesmas)

Manutenção contínua

Tarefa	Cadência	Owner
Sync vault → repo (automático via cron)	diário	CI
Review de logs Cloudflare Access	semanal	Pedro
Review de checklist de tagagem (novos arquivos)	semanal	Pedro / Axios
Atualizar `lista-costal` / `lista-board`	por gatilho	Pedro
Revisão de `publish-contract`	mensal	Pedro
Upgrade Quartz (quando houver release)	trimestral	Anouk devops

Troubleshooting

Sintoma	Causa provável	Solução
`Argumento desconhecido: config`	Quartz v4 não aceita `--config`	Usar env var `AUDIENCE=...` em vez de `--config`
Build falha em `Cannot find module './quartz/plugins/filters/audience-filter'`	Filtro não mergeado no repo	Copiar `filters/*.ts` do scaffold; conferir `filters/index.ts` exporta
Cloudflare Pages retorna 404	`public/` vazio ou path errado	Verificar log do GitHub Action — `quartz build --output`
SSO Google não aparece	IdP não configurado	Zero Trust → Authentication → Login methods
Arquivo sensível apareceu na wiki	Denylist não pegou	Confirmar tag `#sensivel` + `publish: none` + reconstruir
Link quebrado na wiki cliente	Arquivo destino está só em internal	Aceitável (por design) ou tagar destino também para cliente

Colliers × Costal — Interno

Explorador

Deployment Guide — ponta a ponta