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.

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

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 :

pip install mkdocs-material pillow

Chromium installé (pour build-assets.py) :

sudo apt install chromium

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 \
    $WIKI_DIR

Le site_dir dans wiki/mkdocs.yml pointe vers le DocumentRoot Apache configuré dans ISPConfig.

Procédure de déploiement (manuelle)¶

1. Se connecter au serveur¶

ssh <user>@alpinux.org

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

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 :

cd $WIKI_DIR/wiki
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¶

cd $WIKI_DIR/wiki
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 et vérifiez que la modification apparaît bien.

Automatiser avec un script¶

Pour éviter d'oublier une étape, créez un script de déploiement sur le serveur :

#!/bin/bash
set -e

WIKI_DIR="<chemin vers le dépôt sur le serveur>/wiki"

echo "==> Récupération des modifications..."
cd "$WIKI_DIR/.."
git pull

echo "==> Génération du logo..."
cd "$WIKI_DIR"
python3 scripts/build-assets.py

echo "==> Build MkDocs..."
mkdocs build --strict

echo "==> Déployé avec succès sur https://wiki.alpinux.org"

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": "<chemin du script de déploiement>",
    "command-working-directory": "<chemin du dépôt>",
    "response-message": "Déploiement lancé"
  }
]

Démarrez le service :

sudo systemctl enable --now webhook

Côté Gitea : configurer le webhook¶

Allez dans le dépôt sur Gitea → Paramètres → Webhooks → Ajouter un webhook.
URL : http://<serveur>:<port>/hooks/deploy-wiki
Type de déclencheur : Push (ou Pull Request merging)
Cliquez sur Ajouter le webhook.

À chaque push sur main, Gitea appelle l'URL, qui déclenche le script de déploiement.

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