Configuration Cloudflare Pages¶

Ce document décrit les actions manuelles nécessaires pour déployer Serpe sur Cloudflare Pages : création du projet, paramètres de build, et configuration des variables d'environnement.

Important — noms des variables d'environnement Sur ce projet, runtimeConfig dans nuxt.config.ts est câblé explicitement depuis process.env.* avec des noms métier, sans préfixe NUXT_ (Nuxt applique normalement un préfixe NUXT_ par convention, mais ici le mapping est fait à la main). Il faut donc renseigner les variables Cloudflare avec les noms exacts listés à l'étape 4 ci-dessous — pas de préfixe NUXT_.

Prérequis¶

Un compte Cloudflare avec accès à Workers & Pages.
Le dépôt GitHub du projet Serpe accessible (droits d'installation de l'app GitHub Cloudflare Pages sur ce repo, ou org).
Les valeurs finales des secrets (clés API, credentials Google/Supabase) — voir docs/SETUP_GOOGLE.md et docs/SETUP_SUPABASE.md.

Étape 1 — Créer le projet Pages¶

Dashboard Cloudflare > Workers & Pages > Create application > Pages > Connect to Git.
Sélectionnez le dépôt GitHub du projet Serpe.
Nom du projet : serpe-ao-poc (doit correspondre au name déclaré dans wrangler.toml).
Configuration des branches :
Branche de production : main.
Toute Pull Request déclenche automatiquement un déploiement de preview (comportement par défaut de Cloudflare Pages, rien à configurer explicitement).

Étape 2 — Paramètres de build¶

Dans les réglages de build du projet Pages :

Paramètre	Valeur
Framework preset	Nuxt (ou None)
Build command	`npm run build`
Build output directory	`dist`
Root directory	`/` (racine du repo)

Le preset Nitro cloudflare-pages génère le worker dans dist/ (et non .output/public).

Pas de wrangler.toml. Le projet n'utilise volontairement PAS de wrangler.toml : dès qu'il existe, Cloudflare Pages passe en mode « variables gérées par wrangler.toml » et n'accepte plus que des Secrets chiffrés côté dashboard (les variables plaintext par branche sont ignorées). Toute la configuration ci-dessous se fait donc dans le dashboard, ce qui permet des variables plaintext par environnement.

Étape 3 — Activer la compatibilité Node.js (`nodejs_compat`)¶

Nuxt/Nitro (SSR, AsyncLocalStorage) et certaines dépendances serveur utilisent des API Node.js. Le flag nodejs_compat est requis à l'exécution sur le runtime Cloudflare Workers.

Comme il n'y a pas de wrangler.toml, ajoutez-le manuellement dans le dashboard, pour les environnements Production ET Preview :

Settings → Functions (ou Runtime) → Compatibility flags : ajoutez nodejs_compat aux deux environnements.
Compatibility date : 2025-07-15 (ou plus récente) sur les deux.

Sans ce flag, le worker échoue au démarrage (nodejs_compat manquant).

Étape 4 — Variables d'environnement¶

Dans Settings > Environment variables, configurez les variables suivantes pour l'environnement Production (et, si des valeurs de test séparées existent, pour Preview). Utilisez les noms exacts ci-dessous — ce sont les noms métier lus directement par process.env.* dans nuxt.config.ts, sans préfixe NUXT_ :

Provider de génération IA¶

Gemini/Vertex AI est l'unique provider de génération (Claude/Anthropic et Mistral ont été retirés du projet).

Variable	Description
`DEFAULT_GENERATION_PROVIDER`	Provider par défaut (`gemini` par défaut si absent).

Google Cloud / Vertex AI (Gemini)¶

Variable	Description
`GOOGLE_CLOUD_PROJECT`	ID du projet GCP.
`GOOGLE_CLOUD_LOCATION`	Région Vertex AI (`europe-west4` par défaut si absent).
`GOOGLE_GENAI_USE_ENTERPRISE`	`True` pour utiliser Vertex AI (plutôt que l'API Gemini publique).
`GOOGLE_SERVICE_ACCOUNT_JSON`	Contenu JSON complet (une ligne) du compte de service. Requis sur Cloudflare Workers.

Important — pas de système de fichiers sur Cloudflare Workers : en local, l'authentification Google passe par GOOGLE_APPLICATION_CREDENTIALS (chemin vers le fichier service-account.json, voir docs/SETUP_GOOGLE.md). Ce mécanisme basé sur un fichier n'est pas utilisable sur le runtime Cloudflare Workers (pas d'accès au système de fichiers). Sur Cloudflare, il faut donc impérativement définir GOOGLE_SERVICE_ACCOUNT_JSON avec le contenu JSON complet du compte de service (le fichier service-account.json collé tel quel sur une seule ligne dans le champ Cloudflare) : le code applicatif (server/utils/generation/providers/gemini.ts) détecte cette variable en priorité et l'utilise pour construire les credentials en mémoire, sans passer par le disque.

Supabase¶

Variable	Description
`SUPABASE_URL`	URL du projet Supabase (`https://<project-ref>.supabase.co`).
`SUPABASE_ANON_KEY`	Clé publique anonyme. (`SUPABASE_KEY` fonctionne aussi — c'est le nom historique lu en priorité par `@nuxtjs/supabase`, mais `SUPABASE_ANON_KEY` est celui utilisé dans `.env.example` et fonctionne également en fallback.)
`SUPABASE_SERVICE_ROLE_KEY`	Clé service_role (secrète, accès serveur uniquement — lue à la fois par `runtimeConfig.supabaseServiceRoleKey` dans `nuxt.config.ts` et par le module `@nuxtjs/supabase`).

Autres¶

Variable	Description
`ALLOWED_EMAIL_DOMAIN`	Doit rester cohérent avec `app_config.allowed_email_domain` (voir SETUP_SUPABASE.md). Utilisé côté outillage/doc plutôt que lu directement par `nuxt.config.ts` — la source de vérité pour l'application reste le trigger SQL.
`ADMIN_EMAIL`	Idem, cohérence avec `app_config.admin_email`.
`NUXT_UI_PRO_LICENSE`	Laisser vide tant qu'aucune licence Nuxt UI Pro n'est utilisée.

Les identifiants Google OAuth (GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET, voir docs/SETUP_GOOGLE.md) sont collés directement dans le dashboard Supabase (Authentication > Providers > Google), pas dans les variables d'environnement Cloudflare — l'application Nuxt ne les lit pas elle-même.

[vars] DEFAULT_GENERATION_PROVIDER = "gemini" est déjà présent dans wrangler.toml comme valeur par défaut non sensible ; la variable d'environnement Cloudflare Pages (si définie) prend le pas dessus au déploiement.

Étape 5 — Ne jamais commiter de valeurs réelles¶

.env est ignoré par Git (voir .gitignore) — ne jamais forcer son ajout.
.env.example ne doit contenir que des clés vides ou des valeurs non sensibles (ex. GOOGLE_CLOUD_LOCATION=europe-west4, DEFAULT_GENERATION_PROVIDER=gemini).
Toutes les valeurs réelles (JSON du compte de service Google, service_role Supabase) ne doivent exister que dans le dashboard Cloudflare Pages (chiffrées au repos) et dans le .env local de chaque développeur, jamais dans un commit, un ticket ou un message.
Si un secret a été exposé accidentellement (commit, log, capture d'écran), révoquez-le et régénérez-en un nouveau immédiatement (Google Cloud IAM, Supabase API settings).

Étape 6 — Déclencher et vérifier le déploiement¶

Poussez sur main (ou ouvrez une PR pour un déploiement de preview).
Suivez le build dans l'onglet Deployments du projet Pages.
Une fois déployé, vérifiez que l'application répond, que la connexion Google SSO fonctionne (docs/SETUP_GOOGLE.md) et qu'elle communique bien avec Supabase (docs/SETUP_SUPABASE.md).

Récapitulatif des vérifications¶

[ ] Projet Pages serpe-ao-poc créé et connecté au repo GitHub.
[ ] main = production, PR = preview.
[ ] Build command npm run build, output dist.
[ ] Flag nodejs_compat actif en Production et Preview.
[ ] Toutes les variables d'environnement (noms métier, sans préfixe NUXT_) renseignées avec les vraies valeurs, aucune valeur réelle commitée.