From cf03c2fcec8b69b0562a033e8111f79d7b5aaa5c Mon Sep 17 00:00:00 2001 From: Alpinux Date: Sat, 19 Sep 2026 21:04:14 +0200 Subject: [PATCH] =?UTF-8?q?Mettre=20la=20documentation=20de=20d=C3=A9ploie?= =?UTF-8?q?ment=20=C3=A0=20jour=20pour=20ce=20d=C3=A9p=C3=B4t?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ces pages ont été écrites du temps du monorepo et décrivaient encore un clone de alpinux.site.2026 avec un sous-dossier wiki/, ainsi qu'un déploiement par rsync depuis un poste local — alors que le serveur construit le site lui-même, déclenché par un webhook Gitea. - contribuer.md, linux-mint-guide.md, l'article Linux Mint : liens et URL raw vers alpinux-wiki. L'URL de install.sh redevient valide au passage : elle pointait sur code/ à la racine, chemin qui n'existait pas dans le monorepo. - deploiement-wiki.md : chemins sans le sous-dossier wiki/, script de déploiement réel (build en staging), webhook décrit comme le mode normal et non plus comme une option, avec la mise en garde qu'il n'écoute que ce dépôt. - README.md : flux de publication réel, et le -d indispensable au build local puisque site_dir vise le DocumentRoot du serveur. deploiement-dynamic.md mentionne lui aussi un clone du monorepo, mais il concerne l'application dynamic : à corriger avec son dépôt, pas ici. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG --- README.md | 43 +++++---- ...tallation - Linux Mint (depuis Windows).md | 2 +- docs/contribuer.md | 6 +- docs/presentations/linux-mint-guide.md | 2 +- docs/technique/deploiement-wiki.md | 90 +++++++++---------- 5 files changed, 69 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 5afcd4e..8407ea8 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,36 @@ Documentation, guides et ressources du LUG Alpinux — Savoie. Accessible sur `https://wiki.alpinux.org`. -Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le site HTML est généré localement et synchronisé sur le serveur par rsync. +Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le site HTML est généré **sur le serveur**, à chaque push sur `main`. --- ## Flux de publication ``` -Modifier wiki/ → git add / commit → git push → mkdocs build → rsync vers serveur +Modifier → git commit → git push → webhook Gitea → git pull + mkdocs build sur le serveur ``` ```bash -# 1. Versionner git add . git commit -m "..." git push # → gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki - -# 2. Construire et déployer -mkdocs build --strict -rsync -rlcz --delete site/ alpinux.org:/var/www/clients/client1/web2/web/wiki-static/ ``` -> Le `site/` généré n'est pas versionné (dans `.gitignore`). -> La commande rsync cible directement le DocumentRoot ISPConfig du wiki. +C'est tout : le push suffit. Le webhook déclenche `deploy-wiki.sh` sur le serveur, qui +construit le site dans un répertoire de staging et ne le met en ligne que si le build a +réussi. La procédure complète, et quoi faire quand le webhook ne répond pas, sont +décrites dans [Déploiement du wiki](docs/technique/deploiement-wiki.md). + +> Le webhook est attaché à **ce** dépôt. Un push dans l'ancien monorepo +> `alpinux.site.2026` ne publie rien. --- ## Structure des sources ``` -wiki/ +. ├── mkdocs.yml # Configuration MkDocs (nav, thème, plugins) ├── docs/ # Pages Markdown │ ├── index.md @@ -44,27 +44,32 @@ wiki/ ├── overrides/ # Surcharges du thème Material ├── articles/ # Articles longs (hors nav principale) ├── code/ # Exemples de code référencés dans le wiki -└── scripts/ # Scripts utilitaires +└── scripts/ # Scripts utilitaires (build-assets.py) ``` +Les images des articles ne sont pas versionnées : elles sont hébergées sur +`static.alpinux.org`. Le logo PNG est généré depuis le SVG par `scripts/build-assets.py`. + --- ## Développement local ```bash -cd wiki python3 -m venv venv && source venv/bin/activate pip install mkdocs-material mkdocs serve # → http://localhost:8000 (rechargement automatique à chaque modification) ``` -Pour vérifier que le build est propre (liens, structure) : +Pour vérifier que le build est propre (liens, structure) avant de pousser : ```bash -mkdocs build --strict +mkdocs build --strict -d /tmp/wiki-build ``` +> Le `-d` est nécessaire en local : le `site_dir` de `mkdocs.yml` pointe vers le +> DocumentRoot Apache du serveur, pas vers un chemin local. + --- ## Déploiement serveur (ISPConfig) @@ -73,15 +78,7 @@ Le wiki est servi statiquement par Apache via ISPConfig : - DocumentRoot : `/var/www/clients/client1/web2/web/wiki-static` - Let's Encrypt SSL activé -- Aucun service à redémarrer après rsync - -### Première synchronisation - -```bash -ssh alpinux.org "sudo mkdir -p /var/www/clients/client1/web2/web/wiki-static" -mkdocs build --strict -rsync -rlcz --delete site/ alpinux.org:/var/www/clients/client1/web2/web/wiki-static/ -``` +- Aucun service à redémarrer après un déploiement --- diff --git a/articles/Guide d'installation - Linux Mint (depuis Windows).md b/articles/Guide d'installation - Linux Mint (depuis Windows).md index ffd368d..28021c5 100644 --- a/articles/Guide d'installation - Linux Mint (depuis Windows).md +++ b/articles/Guide d'installation - Linux Mint (depuis Windows).md @@ -570,7 +570,7 @@ wget http://10.0.0.1/install.sh oubien pour un accès depuis Internet : ```Bash -wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026/raw/branch/main/code/linux/linux-mint/install.sh +wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/raw/branch/main/code/linux/linux-mint/install.sh ``` puis dans tous les cas : diff --git a/docs/contribuer.md b/docs/contribuer.md index 9920e29..306cc86 100644 --- a/docs/contribuer.md +++ b/docs/contribuer.md @@ -72,7 +72,7 @@ C'est la façon la plus simple de contribuer : corriger une faute, compléter un ### Trouver la page dans le dépôt 1. Allez sur le dépôt du wiki : - **[https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026)** + **[https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki)** 2. Cliquez sur le dossier **`docs/`** — c'est là que se trouvent toutes les pages du wiki. @@ -327,12 +327,12 @@ Résultat : - [Éditeur Markdown en ligne (aperçu temps réel)](https://markdownlivepreview.com/) - [Référence complète Markdown](https://www.markdownguide.org/basic-syntax/) - [Documentation MkDocs Material](https://squidfunk.github.io/mkdocs-material/reference/) -- Dépôt du wiki : [gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026) +- Dépôt du wiki : [gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki) --- ## Une question ? Un problème ? - Posez votre question lors d'une **réunion Alpinux** (1er et 3e jeudis du mois) -- Ouvrez une **issue** directement sur Gitea : [Nouvelle issue](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026/issues/new) +- Ouvrez une **issue** directement sur Gitea : [Nouvelle issue](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/issues/new) - Rejoignez le salon **Matrix** de l'association diff --git a/docs/presentations/linux-mint-guide.md b/docs/presentations/linux-mint-guide.md index ffd368d..28021c5 100644 --- a/docs/presentations/linux-mint-guide.md +++ b/docs/presentations/linux-mint-guide.md @@ -570,7 +570,7 @@ wget http://10.0.0.1/install.sh oubien pour un accès depuis Internet : ```Bash -wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026/raw/branch/main/code/linux/linux-mint/install.sh +wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/raw/branch/main/code/linux/linux-mint/install.sh ``` puis dans tous les cas : diff --git a/docs/technique/deploiement-wiki.md b/docs/technique/deploiement-wiki.md index 5d2f265..0b7ef70 100644 --- a/docs/technique/deploiement-wiki.md +++ b/docs/technique/deploiement-wiki.md @@ -61,11 +61,11 @@ sudo apt install chromium - 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.site.2026.git \ +git clone https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki.git \ $WIKI_DIR ``` -- Le `site_dir` dans `wiki/mkdocs.yml` pointe vers le DocumentRoot Apache configuré dans ISPConfig. +- Le `site_dir` dans `mkdocs.yml` pointe vers le DocumentRoot Apache configuré dans ISPConfig. --- @@ -91,7 +91,7 @@ Vérifiez que la commande affiche bien les fichiers modifiés. Si elle affiche ` Le logo PNG n'est pas dans git — il est généré depuis le SVG source : ```bash -cd $WIKI_DIR/wiki +cd $WIKI_DIR python3 scripts/build-assets.py ``` @@ -107,7 +107,7 @@ Cette commande produit : ### 4. Lancer le build MkDocs ```bash -cd $WIKI_DIR/wiki +cd $WIKI_DIR mkdocs build --strict ``` @@ -131,72 +131,70 @@ Ouvrez [https://wiki.alpinux.org](https://wiki.alpinux.org) et vérifiez que la ## Automatiser avec un script -Pour éviter d'oublier une étape, créez un script de déploiement sur le serveur : +Un script de déploiement (`deploy-wiki.sh`) est en place sur le serveur. Il enchaîne les +étapes ci-dessus avec une précaution supplémentaire : le build est fait dans un répertoire +de *staging*, recopié vers le DocumentRoot seulement si MkDocs a réussi. Un lien cassé ne +peut donc pas laisser le site à moitié construit. ```bash #!/bin/bash set -e -WIKI_DIR="/wiki" +WIKI_DIR="" +STAGING="" +TARGET="" echo "==> Récupération des modifications..." -cd "$WIKI_DIR/.." -git pull +cd "$WIKI_DIR" +git pull origin main echo "==> Génération du logo..." -cd "$WIKI_DIR" python3 scripts/build-assets.py -echo "==> Build MkDocs..." -mkdocs build --strict +echo "==> Build MkDocs (dans le staging)..." +rm -rf "$STAGING" +mkdocs build --strict -d "$STAGING" + +echo "==> Mise en ligne..." +rsync -rltD --no-perms --omit-dir-times --delete "$STAGING/" "$TARGET/" echo "==> Déployé avec succès sur https://wiki.alpinux.org" ``` --- -## Automatiser avec un hook Gitea (optionnel) +## Déploiement automatique par webhook -Pour que le déploiement se déclenche automatiquement à chaque fusion de pull request, configurez un **webhook** dans Gitea. +En temps normal, **il n'y a rien à faire** : un webhook Gitea déclenche le déploiement à +chaque push sur `main`. La procédure manuelle ci-dessus ne sert qu'en cas de panne du +webhook, ou pour rejouer un build sans nouveau commit. -### Côté serveur : créer un endpoint HTTP minimal +``` +push sur main → webhook Gitea → service d'écoute (local au serveur) → deploy-wiki.sh +``` -Installez un petit serveur de webhook (ex. [`webhook`](https://github.com/adnanh/webhook)) : +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`. + +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. + +!!! warning "Un webhook par dépôt" + Le webhook est attaché au dépôt `alpinux-wiki`. Un push ailleurs — en particulier dans + l'ancien monorepo `alpinux.site.2026` — ne déclenche aucun déploiement. + +### Vérifier que le déploiement a bien eu lieu + +Le script journalise chaque exécution. Sur le serveur : ```bash -sudo apt install webhook +tail -20 /var/log/wiki-deploy.log ``` -Créez `/etc/webhook/hooks.json` : - -```json -[ - { - "id": "deploy-wiki", - "execute-command": "", - "command-working-directory": "", - "response-message": "Déploiement lancé" - } -] -``` - -Démarrez le service : - -```bash -sudo systemctl enable --now webhook -``` - -### Côté Gitea : configurer le webhook - -1. Allez dans le dépôt sur Gitea → **Paramètres** → **Webhooks** → **Ajouter un webhook**. -2. **URL** : `http://:/hooks/deploy-wiki` -3. **Type de déclencheur** : *Push* (ou *Pull Request merging*) -4. Cliquez sur **Ajouter le webhook**. - -À chaque push sur `main`, Gitea appelle l'URL, qui déclenche le script de déploiement. - -!!! warning "Sécurité" - Protégez le webhook avec un **secret** (paramètre `trigger-rule` dans `hooks.json` + champ *Secret* dans Gitea) pour éviter que n'importe qui puisse déclencher un build. +Une exécution réussie encadre le build par une ligne `Deploy started` et une ligne +`Deploy done`. ---