ce1f58d652
Le README et les pages de contribution se contredisaient : « éditer la page dans Gitea » ignorait la bifurcation devenue la règle, le tableau d'aiguillage ne connaissait pas trois des pages existantes, et le délai de publication n'était pas le même des deux côtés. Le README oriente désormais, le wiki explique — une seule source de vérité par sujet. Nouvelle page « Relire et fusionner » : ce que fusionner publie, la relecture, la vérification du build, les pièges du poste — renommer une page casse son adresse, aucune redirection n'est installée. Au passage, trois points où les pages ne se répondaient pas : la publication immédiate depuis Obsidian ne concerne que le clone du dépôt du wiki, la bifurcation se remet à jour après chaque fusion, et l'accueil renvoyait au Markdown générique plutôt qu'à notre page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BE4rvHVETRoWnYNDTGssdo
215 lines
6.7 KiB
Markdown
215 lines
6.7 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`.
|
||
|
||
---
|
||
|
||
## 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` |
|
||
| Régénérer les fichiers du logo (poste local) | `python3 scripts/build-assets.py` |
|