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)

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 NxPay 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.