diff --git a/docs/contribuer.md b/docs/contribuer.md index b244c7b..9920e29 100644 --- a/docs/contribuer.md +++ b/docs/contribuer.md @@ -228,6 +228,8 @@ C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`. La publication n'est pas instantanée : un mainteneur doit déclencher le build après la fusion de votre PR. En pratique, les nouveaux articles apparaissent **dans les 24 à 48 heures** suivant la fusion. +Les mainteneurs peuvent consulter la [procédure de déploiement](technique/deploiement-wiki.md) pour les détails techniques. + --- ## Écrire en Markdown {#ecrire-en-markdown} diff --git a/docs/technique/deploiement-wiki.md b/docs/technique/deploiement-wiki.md new file mode 100644 index 0000000..0ca9c28 --- /dev/null +++ b/docs/technique/deploiement-wiki.md @@ -0,0 +1,210 @@ +--- +description: Procédure de déploiement du wiki Alpinux — push Gitea, build MkDocs sur le serveur, mise en ligne sur wiki.alpinux.org. +--- + +# Déploiement du wiki + +Cette page décrit comment mettre en ligne une nouvelle version du wiki après avoir fusionné des contributions sur Gitea. + +!!! note "Pour qui ?" + Cette procédure s'adresse aux mainteneurs ayant accès SSH au serveur `alpinux.org`. + Les contributeurs n'ont rien à faire : leur travail s'arrête à la pull request. + +--- + +## Vue d'ensemble + +``` +Gitea (origin/main) + │ + │ git pull (sur le serveur) + ▼ +Dépôt local serveur + │ + │ mkdocs build + ▼ +/var/www/clients/client1/web2/web/wiki-static/ + │ + │ Apache + ▼ +https://wiki.alpinux.org +``` + +--- + +## Prérequis côté serveur + +- Python 3 et pip installés +- MkDocs et le thème Material installés : + +```bash +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.site.2026.git \ + /home/alpinux/wiki +``` + +- Le `site_dir` dans `mkdocs.yml` pointe vers le bon DocumentRoot Apache : + +```yaml +site_dir: /var/www/clients/client1/web2/web/wiki-static +``` + +--- + +## Procédure de déploiement (manuelle) + +### 1. Se connecter au serveur + +```bash +ssh alpinux@alpinux.org +``` + +### 2. Récupérer les dernières modifications + +```bash +cd /home/alpinux/wiki +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. Lancer le build MkDocs + +```bash +mkdocs build --strict +``` + +L'option `--strict` traite les avertissements comme des erreurs — utile pour détecter les liens cassés avant de mettre en ligne. + +Si tout se passe bien, vous verrez : + +``` +INFO - Building documentation... +INFO - Cleaning site directory +INFO - Documentation built in X.XX seconds +``` + +Le dossier `site_dir` est maintenant mis à jour. Apache sert immédiatement les nouveaux fichiers — **pas besoin de redémarrer Apache**. + +### 4. Vérifier en ligne + +Ouvrez [https://wiki.alpinux.org](https://wiki.alpinux.org) et vérifiez que la modification apparaît bien. + +--- + +## Automatiser avec un script + +Pour éviter d'oublier une étape, créez un script `/home/alpinux/deploy-wiki.sh` : + +```bash +#!/bin/bash +set -e + +WIKI_DIR="/home/alpinux/wiki" + +echo "==> Récupération des modifications..." +cd "$WIKI_DIR" +git pull + +echo "==> Build MkDocs..." +mkdocs build --strict + +echo "==> Déployé avec succès sur https://wiki.alpinux.org" +``` + +Rendez-le exécutable : + +```bash +chmod +x /home/alpinux/deploy-wiki.sh +``` + +Utilisation : + +```bash +/home/alpinux/deploy-wiki.sh +``` + +--- + +## Automatiser avec un hook Gitea (optionnel) + +Pour que le déploiement se déclenche automatiquement à chaque fusion de pull request, configurez un **webhook** dans Gitea. + +### Côté serveur : créer un endpoint HTTP minimal + +Installez un petit serveur de webhook (ex. [`webhook`](https://github.com/adnanh/webhook)) : + +```bash +sudo apt install webhook +``` + +Créez `/etc/webhook/hooks.json` : + +```json +[ + { + "id": "deploy-wiki", + "execute-command": "/home/alpinux/deploy-wiki.sh", + "command-working-directory": "/home/alpinux/wiki", + "response-message": "Déploiement lancé" + } +] +``` + +Démarrez le service : + +```bash +sudo systemctl enable --now webhook +``` + +Le webhook écoute par défaut sur le port `9000`. + +### Côté Gitea : configurer le webhook + +1. Allez dans le dépôt sur Gitea → **Paramètres** → **Webhooks** → **Ajouter un webhook**. +2. **URL** : `http://alpinux.org:9000/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. + +--- + +## En cas d'erreur de build + +Si `mkdocs build` échoue, le site en ligne **n'est pas modifié** — l'ancien contenu reste en place. Lisez le message d'erreur : il indique généralement le fichier et la ligne problématiques. + +Erreurs courantes : + +| Erreur | Cause probable | +|---|---| +| `WARNING - Doc file not found` | Lien mort dans un fichier `.md` | +| `ERROR - Config value 'nav'` | Un fichier listé dans `mkdocs.yml` n'existe pas | +| `ModuleNotFoundError` | Un plugin MkDocs n'est pas installé (`pip install ...`) | + +Pour tester en local avant de pousser : + +```bash +mkdocs serve +``` + +Ouvrez [http://localhost:8000](http://localhost:8000) — MkDocs recharge automatiquement à chaque modification. + +--- + +## Résumé des commandes + +| Action | Commande | +|---|---| +| Mettre à jour le dépôt serveur | `git pull` | +| Construire et déployer | `mkdocs build --strict` | +| Tester en local | `mkdocs serve` | +| Déployer via script | `/home/alpinux/deploy-wiki.sh` | diff --git a/mkdocs.yml b/mkdocs.yml index 669006b..b377be8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -86,6 +86,7 @@ nav: - guides/tesseract.md - guides/ventoy.md - Technique: + - technique/deploiement-wiki.md - technique/git.md - technique/nextcloud.md - technique/matrix.md