Alpinux d4f125f2f6 initial commit — migration depuis monorepo alpinux.site.2026

2026-05-03 17:48:11 +02:00

6 KiB

Raw Blame History

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 :

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.

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

6 KiB Raw Blame History Unescape Escape