Déploiement de la doc — Cloudflare Pages

Cette page décrit comment la doc VitePress (le site que tu lis actuellement) est construite, déployée et hébergée.

URL publique

https://docs.paywithnex.com

Stack

Élément	Choix
Source	apps/docs/ (VitePress, Markdown)
Build	pnpm --filter @nex/docs build → apps/docs/dist/
Hébergement	Cloudflare Pages (projet nex-docs, mode Direct Upload)
CDN	Cloudflare Edge Network (200+ POP, dont Brazzaville)
TLS	Géré automatiquement par Cloudflare
DNS	Zone paywithnex.com (Cloudflare)

Protection d'accès

Le site est protégé par un middleware HTTP Basic Auth exécuté à l'edge Cloudflare (apps/docs/functions/_middleware.js).

Configuration côté Cloudflare Pages

Dashboard → Workers & Pages → projet nex-docs → Settings → Environment variables → Production :

Variable	Type	Valeur
BASIC_AUTH_USER	Plain text	identifiant partagé (ex. nex-auditor)
BASIC_AUTH_PASS	Encrypt	mot de passe fort généré ≥ 24 caractères
BASIC_AUTH_DISABLED	(à omettre en prod)	true uniquement pour debug temporaire

Limites : Basic Auth = un seul couple user/password partagé, popup browser, pas d'audit log natif. Adapté pour bloquer le crawl public et donner un accès partagé à un cercle restreint.

Roadmap — migration vers Cloudflare Access (Zero Trust)

Le Basic Auth est une étape transitoire. La cible long terme :

• Cloudflare Access sur le projet Pages → login email OTP individuel.
• Liste blanche d'emails ou de domaines (@paywithnex.com, @partenaire-banque.com).
• Audit log natif : qui s'est connecté, quand, depuis quelle IP.
• Sessions temporaires : invitation d'un auditeur externe pour 30 jours, accès auto-révoqué.
• Plan free Zero Trust = 50 users inclus.

Setup (10 min via dashboard) :

1. Cloudflare → Zero Trust → Access → Applications → Add application → Self-hosted.
2. Application domain : docs.paywithnex.com.
3. Identity providers : One-time PIN (email).
4. Policies : Allow avec critère Emails ending in ... ou liste d'emails individuels.
5. Désactiver le middleware Basic Auth via BASIC_AUTH_DISABLED=true.

Flow CI/CD

Trigger	Job	Cible
Push sur main (avec changement dans apps/docs/**)	docs:deploy-prod	docs.paywithnex.com (production)
MR (manuel)	docs:deploy-preview	https://<branch-slug>.nex-docs.pages.dev (preview temporaire)

Le job CI est défini dans infrastructure/cicd/deploy-docs.yml.

Détail du job production

1. Installation des dépendances pnpm (uniquement le workspace @nex/docs et ses deps)
2. Build VitePress → apps/docs/dist
3. Upload sur Cloudflare Pages via wrangler pages deploy
4. Cloudflare publie automatiquement sur docs.paywithnex.com (branche main)

Preview MR

Pour valider visuellement une mise à jour de doc avant merge :

1. Sur la MR, déclencher manuellement le job docs:deploy-preview (bouton ▶️)
2. URL temporaire : https://<branch-slug>.nex-docs.pages.dev
3. La preview est nettoyée automatiquement par Cloudflare après 1 semaine d'inactivité

Prérequis (one-time setup)

1. Côté Cloudflare

• Créer le projet Pages nex-docs dans le dashboard Cloudflare (mode Direct Upload)
• Dans l'onglet Custom domains du projet : ajouter docs.paywithnex.com
  • Cloudflare crée automatiquement le record DNS et provisionne le certificat
• Générer un API Token avec :
  • Permission : Account → Cloudflare Pages → Edit
  • Account Resources : compte Nex uniquement
  • Validité : illimitée

2. Côté GitLab CI/CD

Settings > CI/CD > Variables — ajouter (masked + protected) :

Variable	Valeur
CLOUDFLARE_ACCOUNT_ID	ID du compte Cloudflare
CLOUDFLARE_API_TOKEN	Token créé à l'étape précédente

Rollback

En cas de regression sur la doc :

1. Aller dans Cloudflare Pages > projet nex-docs > onglet Deployments
2. Cliquer sur un déploiement antérieur
3. Bouton Rollback to this deployment

Pas besoin de relancer un build.

Coût

Gratuit dans le free tier Cloudflare Pages :

• 500 builds / mois
• Bandwidth illimité
• Sites illimités

Pourquoi Cloudflare Pages plutôt que K8s ?

Décision prise lors du setup :

• La doc est statique → pas besoin de pod / runtime
• Cloudflare Pages = outil dédié pour ce cas d'usage (vs K8s = orchestration applicative)
• Maintenance zéro (pas de pod à monitorer, pas de cert à renouveler)
• Vrai CDN global (cache à 200+ POP) vs serving depuis eu-west-3 uniquement
• Preview URL automatique par MR
• Free vs ressources cluster

L'argument "cohérence stack" (tout dans EKS) ne tient pas pour de la doc statique : c'est de l'over-engineering. Si la doc devient un jour interne (auth requise, contenu sensible), on pourra basculer en K8s — c'est juste un Dockerfile à ajouter.