0045. La variante pubblica del sito si pubblica su Cloudflare Workers

• Stato: Accettata
• Data: 2026-09-14
• Decisori: Team BI/ETL
• Contesto correlato: ADR-0043 (il sito), ADR-0044 (l'app e le due varianti)

Contesto

ADR-0044 ha messo la documentazione dentro l'app desktop e ha separato due varianti del sito: app, con le schede pipeline dei clienti, e public, senza nulla di specifico dei clienti. La variante pubblica si può quindi pubblicare anche fuori dall'app, perché la legga chi non ha l'app installata.

GitHub Pages sui repository privati non è disponibile con il piano dell'org, e Gruppo4D ha già un account Cloudflare.

Decisione

La variante public si pubblica come Worker di soli asset statici su Cloudflare Workers, di nome noeva-etl-docs. La procedura è nel runbook.

• Configurazione in docs/.vitepress/wrangler.jsonc, accanto al resto del sito, e non alla radice del repository: noeva-etl non è un Worker, e un wrangler.jsonc in radice lo farebbe sembrare. Gli asset sono ./dist, cioè l'output di pnpm run docs:build nella variante pubblica; dist-app/ non è mai il bersaglio.
• Routing del sito statico: not_found_handling: "404-page" (serve la 404 di VitePress) e html_handling: "auto-trailing-slash". Con questa impostazione Cloudflare serve /pagina da pagina.html e rimanda /pagina.html a /pagina con un 307. Perciò la variante pubblica genera URL senza estensione (cleanUrls, via usesCleanUrls in docs/.vitepress/lib/docs-target.ts), e ogni link è già nella forma canonica. La variante dell'app resta con .html: lì le pagine le serve Tauri, a cui si chiede il file esatto.
• Deploy automatico da main con il workflow Docs deploy: a ogni promozione in produzione il sito pubblicato si allinea. Il workflow salta il deploy con un avviso se mancano i secret CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID, così non resta rosso finché l'account non è collegato.
• Wrangler non è una dipendenza del progetto. Pesa oltre 100 MB (porta con sé il runtime workerd) e allungherebbe ogni pnpm install, in CI e nello stage di build Docker. Lo si lancia con pnpm dlx wrangler@4.131.2, versione fissata, in CI e nel runbook.
• Accesso riservato con Cloudflare Access, policy per dominio email gruppo4d.com. La variante pubblica non contiene nulla dei clienti, ma resta documentazione interna: runbook dell'infrastruttura, convenzioni del team, link a un repository privato. Access si configura nel dashboard, non nel repository.
• Niente URL di anteprima (preview_urls: false): si pubblica solo da main.

Alternative considerate

• Cloudflare Pages. Adatto ai siti statici quanto Workers con asset statici, che però ha un insieme di funzionalità più ampio (Cloudflare documenta la migrazione da Pages a Workers, non il contrario) e lascia aperta la strada a una logica lato server, se un giorno servisse.
• Workers Builds (build fatta da Cloudflare collegando il repository). Richiede di installare l'app GitHub di Cloudflare sull'org e sposta la build fuori dalla CI che il team già usa. Il workflow su GitHub Actions riusa lo stesso setup della CI.
• wrangler come devDependency. Versione fissata dal lockfile, ma al costo di oltre 100 MB in ogni install per un comando che gira solo al deploy.
• Sito aperto a tutti. Possibile, visto che la variante pubblica non contiene dati dei clienti; scartato per il materiale interno che resta. Si può riaprire togliendo la policy Access.

Conseguenze

• Positive. La documentazione è consultabile da browser senza l'app, sempre allineata a main; il deploy non richiede passaggi a mano dopo la prima configurazione.
• Costi. Una prima configurazione nel dashboard Cloudflare (Worker, Access, token) e due secret nel repository, descritte nel runbook. Un secondo workflow su main.
• Vincolo. Chi scrive documenti deve continuare a rispettare le regole della variante pubblica (ADR-0044): quello che non è in APP_ONLY o in un blocco ::: solo-app finisce online a ogni promozione su main.