Déploiement — Cloudflare Pages

État réel (2026-07-05) : le site est EN LIGNE à https://learnpython-5xq.pages.dev, déployé via l'option B (direct upload wrangler). Conséquences : un git push ne redéploie PAS ; après toute modification, refaire python website/build.py puis NODE_OPTIONS=--use-system-ca npx wrangler pages deploy. Un projet direct-upload ne peut pas être converti en projet Git-connecté (il faudrait en recréer un sous un autre nom pour avoir l'option A). Le site embarque le tuteur interactif (functions/api/ask.js + binding Workers AI déclaré dans wrangler.toml).

Ce guide décrit les deux options de mise en ligne du site (généré par website/build.py).

Pourquoi Cloudflare Pages

Gratuit pour ce volume (builds illimités en pratique, bande passante généreuse, HTTPS et CDN inclus).
Builds automatiques sur push : on connecte le repo GitHub une fois, ensuite chaque push sur main reconstruit et publie le site. C'est toute la maintenance.
Déjà utilisé ici : d'autres projets de ce compte tournent déjà sur Cloudflare Pages (ex. permis-cotier.pages.dev), donc compte configuré et habitudes en place.

Alternative honnête : GitHub Pages. Pour un site statique généré par un script Python, GitHub Pages (avec une GitHub Action qui lance le build) ferait exactement aussi bien, gratuitement aussi. Cloudflare est choisi ici par pure cohérence avec les autres projets du compte, pas par supériorité technique.

Option A (recommandée) — connecter le repo GitHub

Une seule configuration, puis tout est automatique.

Ouvrir le dashboard Cloudflare : <https://dash.cloudflare.com>.
Menu de gauche : Workers & Pages → bouton Create → onglet Pages → Connect to Git.
Autoriser l'accès GitHub si demandé, puis sélectionner le repo Glypto/learnpython → Begin setup.
Configuration du build :
- Project name : learnpython (donne l'URL learnpython.pages.dev ; si le nom est pris, Cloudflare en propose un autre).
- Production branch : main.
- Framework preset : None.
- Build command : python website/build.py
- Build output directory : website/dist
Save and Deploy. Le premier build prend 1–2 minutes.

Notes importantes :

Les images de build Cloudflare incluent Python 3 : aucune installation à faire. Et comme build.py est stdlib pur, aucun requirements.txt n'est nécessaire — ne pas en créer un vide, ça ne sert à rien.
Boucle de maintenance ensuite : travailler normalement, puis git push sur main → Cloudflare rebuild et publie tout seul. Rien d'autre à faire, jamais.
Les branches non-main poussées sur GitHub créent des préviews (<hash>.learnpython.pages.dev) sans toucher à la prod — pratique pour vérifier une refonte avant de merger.

Option B — déploiement direct depuis la machine (sans CI)

Utile pour publier sans passer par GitHub (test ponctuel, panne de CI). Nécessite npx (Node) installé.

python website/build.py
NODE_OPTIONS=--use-system-ca npx wrangler pages deploy website/dist --project-name learnpython

Pourquoi NODE_OPTIONS=--use-system-ca : sur cette machine, l'antivirus intercepte le TLS (certificat racine local injecté). Node ne fait pas confiance à ce certificat par défaut et wrangler échoue avec une erreur TLS. Cette variable dit à Node d'utiliser le magasin de certificats Windows, qui contient le certificat de l'antivirus. C'est spécifique à cette machine — ne pas la documenter comme requise ailleurs.

Au premier lancement, wrangler ouvre un navigateur pour s'authentifier sur le compte Cloudflare, puis crée le projet s'il n'existe pas.

Limite honnête de l'option B : elle publie l'état local, pas l'état du repo — facile de publier du contenu non commité sans s'en rendre compte. L'option A reste la référence.

Vérifier que le site marche

Après le premier déploiement, ouvrir l'URL *.pages.dev et vérifier :

L'accueil s'affiche (contenu du README, pas une page blanche).
Le style est appliqué (fond, sidebar, code sur fond distinct) — sinon voir « page blanche / sans style » ci-dessous.
La sidebar liste bien : Accueil, Niveaux, Docs, Git…
Ouvrir une leçon (ex. Niveau 1 → leçon 01-1) : titres, blocs de code, tableaux et checklists rendus correctement.
Cliquer 2–3 liens internes entre pages (leçon → solutions, accueil → roadmap) : aucun 404, aucun lien qui pointe encore vers un .md.
Sur mobile (ou fenêtre étroite) : le menu se replie en haut et s'ouvre au clic.

Erreurs de déploiement courantes

Le build échoue sur Cloudflare. Ouvrir le projet → Deployments → cliquer le déploiement rouge → lire le build log en entier. L'erreur Python y apparaît telle quelle (traceback). Reproduire en local avec python website/build.py : si ça passe en local mais pas chez Cloudflare, c'est presque toujours un fichier non poussé ou une différence de casse dans un nom de fichier (Linux est sensible à la casse, pas Windows).

python: command not found dans le log. Vérifier que la build image du projet est récente : Settings → Build → Build system version → v2 (ou plus). Les images v2 incluent Python 3 par défaut. Au besoin, fixer la version avec une variable d'environnement PYTHON_VERSION (ex. 3.12) dans Settings → Environment variables. Essayer aussi python3 comme commande de build.

Page blanche ou site sans style. Le HTML se charge mais pas style.css : vérifier que le Build output directory est bien website/dist (et pas dist ou website), et que dist/style.css existe après un build local. Les pages référencent le CSS en chemin relatif (style.css, ../style.css…), donc le site marche aussi bien à la racine d'un domaine que dans un sous-chemin.

404 sur toutes les pages sauf l'accueil. Même cause probable : mauvais output directory, Cloudflare n'a publié qu'une partie de dist/.

Après le premier déploiement : noter l'URL

L'URL <project>.pages.dev est permanente (elle ne change jamais tant que le projet existe). Une fois le premier déploiement réussi :

Noter l'URL exacte (ex. https://learnpython.pages.dev) dans MEMORY.md (mémoire du projet) ;
L'ajouter dans README.md à la racine, section « Le site », pour qu'elle soit visible depuis GitHub.

Ne pas sauter cette étape : c'est ce qui évite de rechercher l'URL dans le dashboard à chaque fois.