docs: procédure de déploiement du wiki (git pull + mkdocs build)
Nouveau fichier docs/technique/deploiement-wiki.md : - schéma du flux Gitea → build → Apache - prérequis serveur (pip install mkdocs-material, clone du dépôt) - procédure manuelle pas à pas (git pull, mkdocs build --strict) - script deploy-wiki.sh prêt à l'emploi - automatisation via webhook Gitea + démon webhook - tableau des erreurs courantes et mkdocs serve pour tests locaux mkdocs.yml : page ajoutée en tête de la section Technique docs/contribuer.md : lien vers la page de déploiement depuis l'étape 5 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Cédrix
parent
da8b6e7fee
commit
096edc378e
3 changed files with 213 additions and 0 deletions
|
|
@ -228,6 +228,8 @@ C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`.
|
|||
|
||||
La publication n'est pas instantanée : un mainteneur doit déclencher le build après la fusion de votre PR. En pratique, les nouveaux articles apparaissent **dans les 24 à 48 heures** suivant la fusion.
|
||||
|
||||
Les mainteneurs peuvent consulter la [procédure de déploiement](technique/deploiement-wiki.md) pour les détails techniques.
|
||||
|
||||
---
|
||||
|
||||
## Écrire en Markdown {#ecrire-en-markdown}
|
||||
|
|
|
|||
210
docs/technique/deploiement-wiki.md
Normal file
210
docs/technique/deploiement-wiki.md
Normal file
|
|
@ -0,0 +1,210 @@
|
|||
---
|
||||
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 :
|
||||
|
||||
```bash
|
||||
pip install mkdocs-material
|
||||
```
|
||||
|
||||
- Un clone du dépôt présent sur le serveur (à faire une seule fois) :
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```yaml
|
||||
site_dir: /var/www/clients/client1/web2/web/wiki-static
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Procédure de déploiement (manuelle)
|
||||
|
||||
### 1. Se connecter au serveur
|
||||
|
||||
```bash
|
||||
ssh alpinux@alpinux.org
|
||||
```
|
||||
|
||||
### 2. Récupérer les dernières modifications
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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](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` :
|
||||
|
||||
```bash
|
||||
#!/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 :
|
||||
|
||||
```bash
|
||||
chmod +x /home/alpinux/deploy-wiki.sh
|
||||
```
|
||||
|
||||
Utilisation :
|
||||
|
||||
```bash
|
||||
/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`](https://github.com/adnanh/webhook)) :
|
||||
|
||||
```bash
|
||||
sudo apt install webhook
|
||||
```
|
||||
|
||||
Créez `/etc/webhook/hooks.json` :
|
||||
|
||||
```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 :
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
Ouvrez [http://localhost:8000](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` |
|
||||
|
|
@ -86,6 +86,7 @@ nav:
|
|||
- guides/tesseract.md
|
||||
- guides/ventoy.md
|
||||
- Technique:
|
||||
- technique/deploiement-wiki.md
|
||||
- technique/git.md
|
||||
- technique/nextcloud.md
|
||||
- technique/matrix.md
|
||||
|
|
|
|||
Loading…
Reference in a new issue