alpinux.site.2026/docs/technique/deploiement-wiki.md

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 :

pip install mkdocs-material

• Un clone du dépôt présent sur le serveur (à faire une seule fois) :

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 :

site_dir: /var/www/clients/client1/web2/web/wiki-static

---

Procédure de déploiement (manuelle)

1. Se connecter au serveur

ssh alpinux@alpinux.org

2. Récupérer les dernières modifications

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

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 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 :

#!/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 :

chmod +x /home/alpinux/deploy-wiki.sh

Utilisation :

/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) :

sudo apt install webhook

Créez /etc/webhook/hooks.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 :

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 :

mkdocs serve

Ouvrez 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