c9e2624466
derniers-articles.json s'arrête à vingt entrées : ce qu'il faut pour la section de l'accueil, trop peu pour la page des mises à jour d'alpinux.org, qui veut montrer tout ce que le wiki publie. Le build écrit donc un second fichier, toutes-les-pages.json, sans plafond et avec la rubrique de chaque page — la section de premier niveau de la navigation, celle à laquelle un lecteur range les choses. Un seul parcours de l'historique git produit les deux : le second est la liste entière, le premier son début. derniers-articles.json ne bouge pas d'un octet dans sa forme — mêmes quatre clés, même ordre — pour que l'accueil continue de le lire sans rien savoir de tout ceci. L'en-tête CORS couvre maintenant les deux fichiers, et seulement eux ; le bloc n'est écrit que pour ceux qui manquent au .htaccess, de sorte qu'un second build ne le duplique pas. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JYfYUZRcJmmEWJwAxZb4o2
268 lines
9.5 KiB
Markdown
268 lines
9.5 KiB
Markdown
---
|
||
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.
|
||
|
||
Le versant éditorial du rôle — relire une contribution, vérifier le build, fusionner
|
||
— est décrit dans [Relire et fusionner](../contribuer/mainteneurs.md).
|
||
|
||
---
|
||
|
||
## 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
|
||
```
|
||
|
||
!!! info "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é :
|
||
|
||
```bash
|
||
pip install mkdocs-material
|
||
```
|
||
|
||
- Un clone du dépôt présent sur le serveur (à faire une seule fois) :
|
||
|
||
```bash
|
||
git clone <dépôt alpinux-wiki> $WIKI_DIR
|
||
```
|
||
|
||
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_dir` dans `mkdocs.yml` pointe 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
|
||
|
||
```bash
|
||
ssh <user>@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. 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**.
|
||
|
||
### 4. 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="<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.
|
||
|
||
```
|
||
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. 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.
|
||
|
||
!!! 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`.
|
||
|
||
---
|
||
|
||
## 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 log` avec
|
||
suivi des renommages : déplacer `guides/truc.md` ne 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.
|
||
|
||
!!! warning "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.
|
||
|
||
```bash
|
||
# 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 :
|
||
|
||
```bash
|
||
mkdocs serve
|
||
```
|
||
|
||
Ouvrez [http://localhost:8000](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` |
|