232 lines
6 KiB
Markdown
232 lines
6 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.
|
||
|
||
---
|
||
|
||
## 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 :
|
||
|
||
```bash
|
||
pip install mkdocs-material pillow
|
||
```
|
||
|
||
- Chromium installé (pour `build-assets.py`) :
|
||
|
||
```bash
|
||
sudo apt install chromium
|
||
```
|
||
|
||
- 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 \
|
||
$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
|
||
|
||
```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. 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 :
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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](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 :
|
||
|
||
```bash
|
||
#!/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`](https://github.com/adnanh/webhook)) :
|
||
|
||
```bash
|
||
sudo apt install webhook
|
||
```
|
||
|
||
Créez `/etc/webhook/hooks.json` :
|
||
|
||
```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 :
|
||
|
||
```bash
|
||
sudo systemctl enable --now webhook
|
||
```
|
||
|
||
### Côté Gitea : configurer le webhook
|
||
|
||
1. Allez dans le dépôt sur Gitea → **Paramètres** → **Webhooks** → **Ajouter un webhook**.
|
||
2. **URL** : `http://<serveur>:<port>/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` |
|
||
| 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` |
|