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.
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.
Le versant éditorial du rôle — relire une contribution, vérifier le build, fusionner — est décrit dans Relire et fusionner.
Vue d'ensemble¶
git push (sur main)
│
Gitea (origin/main)
│
│ webhook → deploy-wiki.sh : git pull
▼
Dépôt local serveur
│
│ mkdocs build --strict (dans un staging)
▼
DocumentRoot Apache (wiki.alpinux.org)
│
│ Apache
▼
https://wiki.alpinux.org
Images et logo
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 MkDocs Material, dans un environnement dédié :
- Un clone du dépôt présent sur le serveur (à faire une seule fois) :
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_dirdansmkdocs.ymlpointe vers le DocumentRoot Apache configuré dans ISPConfig.
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¶
2. Récupérer les dernières modifications¶
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¶
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.
4. Vérifier en ligne¶
Ouvrez 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.
#!/bin/bash
set -e
WIKI_DIR="<chemin du dépôt sur le serveur>"
STAGING="<répertoire de staging>"
TARGET="<DocumentRoot du wiki>"
echo "==> Récupération des modifications..."
cd "$WIKI_DIR"
git pull origin main
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.
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.
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 :
Une exécution réussie encadre le build par une ligne Deploy started et une ligne
Deploy done.
Ce que le build publie pour alpinux.org¶
Chaque build écrit deux fichiers à la racine du site, avec pour chaque page son titre, son adresse et la date du commit qui a touché son contenu :
| Fichier | Ce qu'il porte | Qui le lit |
|---|---|---|
derniers-articles.json |
Les vingt dernières pages créées ou modifiées | L'accueil d'alpinux.org, section « Le wiki, fraîchement mis à jour » |
toutes-les-pages.json |
Toutes les pages, sans limite, avec leur rubrique | La page des mises à jour d'alpinux.org |
Le second est la liste entière, le premier son début : un seul parcours de l'historique git les produit tous les deux, et ils portent la même date de génération.
Ils sont produits par le hook hooks/derniers_articles.py, déclaré dans mkdocs.yml.
Trois choses à savoir :
- Un déplacement n'est pas une mise à jour. Les dates viennent de
git logavec suivi des renommages : déplacerguides/truc.mdne fait pas remonter l'article en tête de liste, seule une modification de son texte le fait. - Seules les pages de la navigation sont annoncées. Une page absente de
nav— typiquement la redirection laissée derrière un article déplacé — n'apparaît jamais dans la liste. - Le hook n'échoue jamais. Sans historique git, il n'écrit rien et le build
continue ; alpinux.org masque alors simplement ce qu'il ne peut pas remplir. Ses
messages sont pour cela de niveau info et jamais warning : le déploiement
construit avec
--strict, où un seul avertissement suffit à interrompre le build, et donc la publication.
Le même hook pose l'en-tête Access-Control-Allow-Origin sur ces deux fichiers, et
sur eux seuls, au moyen d'un .htaccess déposé à la racine du site construit. Sans
lui, le navigateur refuserait à alpinux.org le droit de lire une réponse venue de
wiki.alpinux.org.
Deux conditions
Le clone doit avoir son historique. Un clone --depth 1 ne porte qu'un
commit : toutes les pages sembleraient modifiées le même jour. Le hook le détecte
et le signale dans le journal du build, sans rien casser.
Un .htaccess posé à la main sur le serveur est effacé au déploiement suivant,
puisque le staging est recopié avec rsync --delete. Pour ajouter des règles
Apache durables, placez-les dans docs/.htaccess : MkDocs le recopie dans le site
construit, et le hook ajoute son bloc à la suite au lieu de le remplacer.
# vérifier ce que le dernier build a publié
curl -s https://wiki.alpinux.org/derniers-articles.json | head -20
curl -s https://wiki.alpinux.org/toutes-les-pages.json | head -20
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 :
Ouvrez http://localhost:8000 — MkDocs recharge automatiquement à chaque modification.
Résumé des commandes¶
| Action | Commande |
|---|---|
| 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 |
| Vérifier la liste envoyée à l'accueil | curl -s https://wiki.alpinux.org/derniers-articles.json |
| Vérifier l'inventaire complet publié | curl -s https://wiki.alpinux.org/toutes-les-pages.json |
| Régénérer les fichiers du logo (poste local) | python3 scripts/build-assets.py |