Runbook: sito di documentazione su Cloudflare Workers

Pubblica la variante pubblica del sito di documentazione (ADR-0044) come Worker di soli asset statici su Cloudflare (ADR-0045). La variante dell'app, con le schede pipeline dei clienti, non va mai pubblicata qui.

Sintesi

• Cosa fa: builda docs/ nella variante public e la pubblica sul Worker noeva-etl-docs.
• Owner: Team BI/ETL.
• Quando: a ogni push su main, dal workflow Docs deploy (.github/workflows/docs-deploy.yml), oppure a mano.
• Criticità: bassa. Il sito è documentazione: se un deploy si rompe, si torna alla versione precedente.
• Configurazione: docs/.vitepress/wrangler.jsonc.

Prima configurazione (una volta sola)

Serve un utente dell'account Cloudflare di Gruppo4D con i permessi sui Workers, e un amministratore del repository GitHub per i secret.

1. Login di Wrangler con l'account giusto. Wrangler ha un login suo, indipendente da altri strumenti collegati a Cloudflare. Esci da un login precedente, entra con l'account Gruppo4D e controlla email e account:

   pnpm dlx wrangler@4.131.2 logout

   pnpm dlx wrangler@4.131.2 login

   pnpm dlx wrangler@4.131.2 whoami

   Se l'utente vede più account, esporta CLOUDFLARE_ACCOUNT_ID con l'ID di quello di Gruppo4D prima dei comandi successivi.

2. Primo deploy a mano, come in Deploy a mano. Crea il Worker e stampa l'URL https://noeva-etl-docs.<sottodominio>.workers.dev.

3. Cloudflare Access, subito dopo il primo deploy (fino ad allora l'URL è pubblico): dashboard → Workers & Pages → noeva-etl-docs → scheda Access → Protect this Worker behind Access → All traffic → policy Email domain gruppo4d.com → Apply Access. Serve Zero Trust attivo sull'account: se non lo è, il dashboard chiede prima di configurarlo. Verifica da una finestra in incognito che l'URL chieda il login.

4. Secret per il deploy automatico. Nel dashboard: Account API tokens → Create Token → modello Edit Cloudflare Workers, limitato all'account Gruppo4D. Su GitHub, in my-ginkgo/noeva-etl → Settings → Secrets and variables → Actions, crea CLOUDFLARE_API_TOKEN (il token) e CLOUDFLARE_ACCOUNT_ID (l'ID dell'account, da whoami o dal dashboard). Finché mancano, il workflow salta il deploy con un avviso invece di fallire.

Deploy automatico

Ogni push su main builda la variante pubblica e la pubblica. Il workflow si può lanciare anche a mano da GitHub, scheda Actions → Docs deploy → Run workflow. Il gate di qualità resta CI: questo workflow non verifica, pubblica.

Deploy a mano

Dalla radice di noeva-etl, con il login del passo 1 fatto. Build della variante pubblica, che è il default di docs:build:

pnpm run docs:build

Pubblicazione:

pnpm dlx wrangler@4.131.2 deploy --config docs/.vitepress/wrangler.jsonc

⚠️ Mai docs:build:app prima di un deploy: quella build contiene le schede pipeline dei clienti e finisce in dist-app/, che la configurazione non pubblica, ma una copia a mano in dist/ le esporrebbe.

Verifiche dopo un deploy

• L'URL risponde, e senza login da una finestra in incognito chiede l'accesso (Access attivo).
• La sidebar non ha il gruppo "Schede pipeline", e /pipelines/README risponde con la pagina 404.
• Un indirizzo con .html (per esempio /guide/grafo.html) fa un redirect alla forma senza estensione.

Procedure di recovery

Il sito pubblicato è rotto

Torna alla versione precedente del Worker; Wrangler chiede quale:

pnpm dlx wrangler@4.131.2 rollback --config docs/.vitepress/wrangler.jsonc

Poi correggi su dev e promuovi come sempre: il prossimo push su main ripubblica.

Una pagina con contenuti di un cliente è finita online

1. Rollback immediato, come sopra, alla versione precedente senza quella pagina.
2. Sposta il contenuto dove la variante pubblica non lo pubblica: docs/pipelines/, l'elenco APP_ONLY in docs/.vitepress/lib/docs-target.ts, o un blocco ::: solo-app (vedi policy di documentazione).
3. Cerca il nome del cliente nella build pubblica (docs/.vitepress/dist/) prima di ripubblicare.

Il workflow salta il deploy

Nel log compare «deploy saltato»: mancano CLOUDFLARE_API_TOKEN o CLOUDFLARE_ACCOUNT_ID fra i secret del repository (passo 4).

Il deploy fallisce con un errore di autenticazione

Il token è scaduto, revocato o limitato all'account sbagliato: creane uno nuovo (passo 4) e aggiorna il secret.

Escalation

• Primo livello: Team BI/ETL.
• Account Cloudflare e Zero Trust: chi amministra l'account Cloudflare di Gruppo4D.