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