From e3d32ba55d2746f724847d17283366c46fb096c0 Mon Sep 17 00:00:00 2001 From: Alpinux Date: Sat, 19 Sep 2026 21:38:11 +0200 Subject: [PATCH] =?UTF-8?q?Corriger=20ce=20que=20la=20bascule=20a=20r?= =?UTF-8?q?=C3=A9v=C3=A9l=C3=A9=20sur=20le=20d=C3=A9ploiement?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le premier déploiement depuis le nouveau dépôt a montré deux inexactitudes de cette page, héritées de sa rédaction initiale : - le logo n'est pas généré au déploiement. Le thème et les pages chargent le logo depuis static.alpinux.org par URL complète ; build-assets.py ne sert qu'à fabriquer les fichiers à y téléverser, et demande Pillow et Chromium, absents du serveur. L'étape correspondante et les prérequis associés sont retirés, le script de déploiement n'a jamais appelé ce script. - le service d'écoute n'est pas injoignable de l'extérieur : Apache proxifie /deploy vers lui. C'est la signature HMAC qui le protège, pas l'isolement. Au passage : procédure manuelle présentée comme un secours et non comme le mode normal, clone par clé de déploiement en lecture seule, et tableau récapitulatif refait autour du fait que publier se résume à git push. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG --- docs/technique/deploiement-wiki.md | 86 ++++++++++++------------------ 1 file changed, 34 insertions(+), 52 deletions(-) diff --git a/docs/technique/deploiement-wiki.md b/docs/technique/deploiement-wiki.md index 0b7ef70..3ab5523 100644 --- a/docs/technique/deploiement-wiki.md +++ b/docs/technique/deploiement-wiki.md @@ -15,19 +15,15 @@ Cette page décrit comment mettre en ligne une nouvelle version du wiki après a ## Vue d'ensemble ``` -docs/assets/alpinux-logo.svg (source, dans git) - │ - │ build-assets.py (à faire si le SVG a changé) - ▼ -docs/assets/alpinux-logo.png (généré, hors git) + /tmp/ → static.alpinux.org +git push (sur main) │ Gitea (origin/main) │ - │ git pull (sur le serveur) + │ webhook → deploy-wiki.sh : git pull ▼ Dépôt local serveur │ - │ mkdocs build --strict + │ mkdocs build --strict (dans un staging) ▼ DocumentRoot Apache (wiki.alpinux.org) │ @@ -37,39 +33,43 @@ https://wiki.alpinux.org ``` !!! info "Images et logo" - Les fichiers PNG ne sont **pas stockés dans git**. Le logo (`docs/assets/alpinux-logo.png`) - est généré par `build-assets.py` avant le build MkDocs. Les autres images des articles - sont hébergées sur **static.alpinux.org**. + Aucune image n'est stockée dans git : le logo et les illustrations des articles sont + servis depuis **static.alpinux.org**, et les pages y pointent par leur URL complète. + Le déploiement du wiki n'a donc rien à générer. + + `scripts/build-assets.py` ne sert qu'à **produire** les fichiers à téléverser sur + `static.alpinux.org` (logo 200×200, logo 512, favicons) quand le SVG source change. + Il demande Pillow et Chromium, absents du serveur : lancez-le depuis un poste de + travail, puis envoyez le contenu de `/tmp/alpinux-static-assets/` vers + `static.alpinux.org/logo/`. --- ## Prérequis côté serveur -- Python 3 et pip installés -- MkDocs, le thème Material et Pillow installés : +- Python 3 et MkDocs Material, dans un environnement dédié : ```bash -pip install mkdocs-material pillow -``` - -- Chromium installé (pour `build-assets.py`) : - -```bash -sudo apt install chromium +pip install mkdocs-material ``` - Un clone du dépôt présent sur le serveur (à faire une seule fois) : ```bash -git clone https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki.git \ - $WIKI_DIR +git clone $WIKI_DIR ``` + Le serveur tire par une **clé de déploiement** en lecture seule, déclarée dans + *Paramètres → Clés de déploiement* du dépôt : il n'a jamais besoin d'écrire. + - Le `site_dir` dans `mkdocs.yml` pointe vers le DocumentRoot Apache configuré dans ISPConfig. --- -## Procédure de déploiement (manuelle) +## Procédure de déploiement manuelle (secours) + +En temps normal le déploiement est automatique — voir plus bas. Ces étapes servent quand +le webhook ne répond pas, ou pour reconstruire le site sans nouveau commit. ### 1. Se connecter au serveur @@ -86,25 +86,7 @@ git pull Vérifiez que la commande affiche bien les fichiers modifiés. Si elle affiche `Already up to date`, le serveur est déjà à jour. -### 3. Générer le logo (si le SVG a changé) - -Le logo PNG n'est pas dans git — il est généré depuis le SVG source : - -```bash -cd $WIKI_DIR -python3 scripts/build-assets.py -``` - -Cette commande produit : - -- `docs/assets/alpinux-logo.png` — logo 200×200 inclus dans le wiki -- `/tmp/alpinux-static-assets/` — logo 512px + favicons à uploader sur `static.alpinux.org/logo/` - -!!! tip - Si seul le contenu Markdown a changé (aucune modification du SVG), cette étape peut être ignorée. - Le `docs/assets/alpinux-logo.png` du précédent build est toujours présent sur le serveur. - -### 4. Lancer le build MkDocs +### 3. Lancer le build MkDocs ```bash cd $WIKI_DIR @@ -123,7 +105,7 @@ INFO - Documentation built in X.XX seconds Le DocumentRoot Apache est maintenant mis à jour. **Pas besoin de redémarrer Apache**. -### 5. Vérifier en ligne +### 4. Vérifier en ligne Ouvrez [https://wiki.alpinux.org](https://wiki.alpinux.org) et vérifiez que la modification apparaît bien. @@ -148,9 +130,6 @@ echo "==> Récupération des modifications..." cd "$WIKI_DIR" git pull origin main -echo "==> Génération du logo..." -python3 scripts/build-assets.py - echo "==> Build MkDocs (dans le staging)..." rm -rf "$STAGING" mkdocs build --strict -d "$STAGING" @@ -173,10 +152,11 @@ webhook, ou pour rejouer un build sans nouveau commit. push sur main → webhook Gitea → service d'écoute (local au serveur) → deploy-wiki.sh ``` -Le service d'écoute est un petit serveur HTTP lancé par systemd, accessible uniquement -depuis le serveur lui-même. Il vérifie la signature HMAC envoyée par Gitea (en-tête -`X-Gitea-Signature`, secret partagé) avant de lancer quoi que ce soit, et ignore les -push qui ne visent pas `main`. +Le service d'écoute est un petit serveur HTTP lancé par systemd. Il n'écoute que sur la +boucle locale ; Apache lui transmet les requêtes reçues sur `/deploy`. Avant de lancer +quoi que ce soit, il vérifie la signature HMAC envoyée par Gitea (en-tête +`X-Gitea-Signature`, secret partagé) et ignore les push qui ne visent pas `main` — une +requête sans signature valable reçoit un `403`. Côté Gitea, le webhook se configure dans **Paramètres → Webhooks** du dépôt : URL de l'endpoint, déclencheur *Push*, et le même secret que celui du service. @@ -224,7 +204,9 @@ Ouvrez [http://localhost:8000](http://localhost:8000) — MkDocs recharge automa | Action | Commande | |---|---| -| Mettre à jour le dépôt serveur | `git pull` | -| Générer le logo PNG (si SVG modifié) | `python3 scripts/build-assets.py` | -| Construire et déployer | `mkdocs build --strict` | +| Publier | `git push` — le reste est automatique | | Tester en local | `mkdocs serve` | +| Vérifier le build avant de pousser | `mkdocs build --strict -d /tmp/wiki-build` | +| Déployer à la main (webhook en panne) | `deploy-wiki.sh`, sur le serveur | +| Voir le journal des déploiements | `tail -20 /var/log/wiki-deploy.log` | +| Régénérer les fichiers du logo (poste local) | `python3 scripts/build-assets.py` |