--- 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 ``` 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 │ Gitea (origin/main) │ │ git pull (sur le serveur) ▼ Dépôt local serveur │ │ mkdocs build --strict ▼ DocumentRoot Apache (wiki.alpinux.org) │ │ Apache ▼ 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**. --- ## Prérequis côté serveur - Python 3 et pip installés - MkDocs, le thème Material et Pillow installés : ```bash pip install mkdocs-material pillow ``` - Chromium installé (pour `build-assets.py`) : ```bash 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-wiki.git \ $WIKI_DIR ``` - Le `site_dir` dans `mkdocs.yml` pointe vers le DocumentRoot Apache configuré dans ISPConfig. --- ## Procédure de déploiement (manuelle) ### 1. Se connecter au serveur ```bash ssh @alpinux.org ``` ### 2. Récupérer les dernières modifications ```bash cd $WIKI_DIR 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 ```bash cd $WIKI_DIR 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 DocumentRoot Apache est maintenant mis à jour. **Pas besoin de redémarrer Apache**. ### 5. 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 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="" STAGING="" TARGET="" 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" 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" ``` --- ## Déploiement automatique par webhook 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. ``` 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`. 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 tail -20 /var/log/wiki-deploy.log ``` Une exécution réussie encadre le build par une ligne `Deploy started` et une ligne `Deploy done`. --- ## 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` | | Générer le logo PNG (si SVG modifié) | `python3 scripts/build-assets.py` | | Construire et déployer | `mkdocs build --strict` | | Tester en local | `mkdocs serve` |