Mettre la documentation de déploiement à jour pour ce dépôt
Ces pages ont été écrites du temps du monorepo et décrivaient encore un clone de alpinux.site.2026 avec un sous-dossier wiki/, ainsi qu'un déploiement par rsync depuis un poste local — alors que le serveur construit le site lui-même, déclenché par un webhook Gitea. - contribuer.md, linux-mint-guide.md, l'article Linux Mint : liens et URL raw vers alpinux-wiki. L'URL de install.sh redevient valide au passage : elle pointait sur code/ à la racine, chemin qui n'existait pas dans le monorepo. - deploiement-wiki.md : chemins sans le sous-dossier wiki/, script de déploiement réel (build en staging), webhook décrit comme le mode normal et non plus comme une option, avec la mise en garde qu'il n'écoute que ce dépôt. - README.md : flux de publication réel, et le -d indispensable au build local puisque site_dir vise le DocumentRoot du serveur. deploiement-dynamic.md mentionne lui aussi un clone du monorepo, mais il concerne l'application dynamic : à corriger avec son dépôt, pas ici. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG
This commit is contained in:
Alpinux
parent
0ce3d2ae84
commit
cf03c2fcec
5 changed files with 69 additions and 74 deletions
43
README.md
43
README.md
|
|
@ -3,36 +3,36 @@
|
|||
Documentation, guides et ressources du LUG Alpinux — Savoie.
|
||||
Accessible sur `https://wiki.alpinux.org`.
|
||||
|
||||
Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le site HTML est généré localement et synchronisé sur le serveur par rsync.
|
||||
Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le site HTML est généré **sur le serveur**, à chaque push sur `main`.
|
||||
|
||||
---
|
||||
|
||||
## Flux de publication
|
||||
|
||||
```
|
||||
Modifier wiki/ → git add / commit → git push → mkdocs build → rsync vers serveur
|
||||
Modifier → git commit → git push → webhook Gitea → git pull + mkdocs build sur le serveur
|
||||
```
|
||||
|
||||
```bash
|
||||
# 1. Versionner
|
||||
git add .
|
||||
git commit -m "..."
|
||||
git push # → gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki
|
||||
|
||||
# 2. Construire et déployer
|
||||
mkdocs build --strict
|
||||
rsync -rlcz --delete site/ alpinux.org:/var/www/clients/client1/web2/web/wiki-static/
|
||||
```
|
||||
|
||||
> Le `site/` généré n'est pas versionné (dans `.gitignore`).
|
||||
> La commande rsync cible directement le DocumentRoot ISPConfig du wiki.
|
||||
C'est tout : le push suffit. Le webhook déclenche `deploy-wiki.sh` sur le serveur, qui
|
||||
construit le site dans un répertoire de staging et ne le met en ligne que si le build a
|
||||
réussi. La procédure complète, et quoi faire quand le webhook ne répond pas, sont
|
||||
décrites dans [Déploiement du wiki](docs/technique/deploiement-wiki.md).
|
||||
|
||||
> Le webhook est attaché à **ce** dépôt. Un push dans l'ancien monorepo
|
||||
> `alpinux.site.2026` ne publie rien.
|
||||
|
||||
---
|
||||
|
||||
## Structure des sources
|
||||
|
||||
```
|
||||
wiki/
|
||||
.
|
||||
├── mkdocs.yml # Configuration MkDocs (nav, thème, plugins)
|
||||
├── docs/ # Pages Markdown
|
||||
│ ├── index.md
|
||||
|
|
@ -44,27 +44,32 @@ wiki/
|
|||
├── overrides/ # Surcharges du thème Material
|
||||
├── articles/ # Articles longs (hors nav principale)
|
||||
├── code/ # Exemples de code référencés dans le wiki
|
||||
└── scripts/ # Scripts utilitaires
|
||||
└── scripts/ # Scripts utilitaires (build-assets.py)
|
||||
```
|
||||
|
||||
Les images des articles ne sont pas versionnées : elles sont hébergées sur
|
||||
`static.alpinux.org`. Le logo PNG est généré depuis le SVG par `scripts/build-assets.py`.
|
||||
|
||||
---
|
||||
|
||||
## Développement local
|
||||
|
||||
```bash
|
||||
cd wiki
|
||||
python3 -m venv venv && source venv/bin/activate
|
||||
pip install mkdocs-material
|
||||
mkdocs serve
|
||||
# → http://localhost:8000 (rechargement automatique à chaque modification)
|
||||
```
|
||||
|
||||
Pour vérifier que le build est propre (liens, structure) :
|
||||
Pour vérifier que le build est propre (liens, structure) avant de pousser :
|
||||
|
||||
```bash
|
||||
mkdocs build --strict
|
||||
mkdocs build --strict -d /tmp/wiki-build
|
||||
```
|
||||
|
||||
> Le `-d` est nécessaire en local : le `site_dir` de `mkdocs.yml` pointe vers le
|
||||
> DocumentRoot Apache du serveur, pas vers un chemin local.
|
||||
|
||||
---
|
||||
|
||||
## Déploiement serveur (ISPConfig)
|
||||
|
|
@ -73,15 +78,7 @@ Le wiki est servi statiquement par Apache via ISPConfig :
|
|||
|
||||
- DocumentRoot : `/var/www/clients/client1/web2/web/wiki-static`
|
||||
- Let's Encrypt SSL activé
|
||||
- Aucun service à redémarrer après rsync
|
||||
|
||||
### Première synchronisation
|
||||
|
||||
```bash
|
||||
ssh alpinux.org "sudo mkdir -p /var/www/clients/client1/web2/web/wiki-static"
|
||||
mkdocs build --strict
|
||||
rsync -rlcz --delete site/ alpinux.org:/var/www/clients/client1/web2/web/wiki-static/
|
||||
```
|
||||
- Aucun service à redémarrer après un déploiement
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -570,7 +570,7 @@ wget http://10.0.0.1/install.sh
|
|||
oubien pour un accès depuis Internet :
|
||||
|
||||
```Bash
|
||||
wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026/raw/branch/main/code/linux/linux-mint/install.sh
|
||||
wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/raw/branch/main/code/linux/linux-mint/install.sh
|
||||
```
|
||||
|
||||
puis dans tous les cas :
|
||||
|
|
|
|||
|
|
@ -72,7 +72,7 @@ C'est la façon la plus simple de contribuer : corriger une faute, compléter un
|
|||
### Trouver la page dans le dépôt
|
||||
|
||||
1. Allez sur le dépôt du wiki :
|
||||
**[https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026)**
|
||||
**[https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki)**
|
||||
|
||||
2. Cliquez sur le dossier **`docs/`** — c'est là que se trouvent toutes les pages du wiki.
|
||||
|
||||
|
|
@ -327,12 +327,12 @@ Résultat :
|
|||
- [Éditeur Markdown en ligne (aperçu temps réel)](https://markdownlivepreview.com/)
|
||||
- [Référence complète Markdown](https://www.markdownguide.org/basic-syntax/)
|
||||
- [Documentation MkDocs Material](https://squidfunk.github.io/mkdocs-material/reference/)
|
||||
- Dépôt du wiki : [gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026)
|
||||
- Dépôt du wiki : [gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki)
|
||||
|
||||
---
|
||||
|
||||
## Une question ? Un problème ?
|
||||
|
||||
- Posez votre question lors d'une **réunion Alpinux** (1er et 3e jeudis du mois)
|
||||
- Ouvrez une **issue** directement sur Gitea : [Nouvelle issue](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026/issues/new)
|
||||
- Ouvrez une **issue** directement sur Gitea : [Nouvelle issue](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/issues/new)
|
||||
- Rejoignez le salon **Matrix** de l'association
|
||||
|
|
|
|||
|
|
@ -570,7 +570,7 @@ wget http://10.0.0.1/install.sh
|
|||
oubien pour un accès depuis Internet :
|
||||
|
||||
```Bash
|
||||
wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux.site.2026/raw/branch/main/code/linux/linux-mint/install.sh
|
||||
wget https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/raw/branch/main/code/linux/linux-mint/install.sh
|
||||
```
|
||||
|
||||
puis dans tous les cas :
|
||||
|
|
|
|||
|
|
@ -61,11 +61,11 @@ 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 \
|
||||
git clone https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki.git \
|
||||
$WIKI_DIR
|
||||
```
|
||||
|
||||
- Le `site_dir` dans `wiki/mkdocs.yml` pointe vers le DocumentRoot Apache configuré dans ISPConfig.
|
||||
- Le `site_dir` dans `mkdocs.yml` pointe vers le DocumentRoot Apache configuré dans ISPConfig.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ Vérifiez que la commande affiche bien les fichiers modifiés. Si elle affiche `
|
|||
Le logo PNG n'est pas dans git — il est généré depuis le SVG source :
|
||||
|
||||
```bash
|
||||
cd $WIKI_DIR/wiki
|
||||
cd $WIKI_DIR
|
||||
python3 scripts/build-assets.py
|
||||
```
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ Cette commande produit :
|
|||
### 4. Lancer le build MkDocs
|
||||
|
||||
```bash
|
||||
cd $WIKI_DIR/wiki
|
||||
cd $WIKI_DIR
|
||||
mkdocs build --strict
|
||||
```
|
||||
|
||||
|
|
@ -131,72 +131,70 @@ Ouvrez [https://wiki.alpinux.org](https://wiki.alpinux.org) et vérifiez que la
|
|||
|
||||
## Automatiser avec un script
|
||||
|
||||
Pour éviter d'oublier une étape, créez un script de déploiement sur le serveur :
|
||||
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 vers le dépôt sur le serveur>/wiki"
|
||||
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
|
||||
cd "$WIKI_DIR"
|
||||
git pull origin main
|
||||
|
||||
echo "==> Génération du logo..."
|
||||
cd "$WIKI_DIR"
|
||||
python3 scripts/build-assets.py
|
||||
|
||||
echo "==> Build MkDocs..."
|
||||
mkdocs build --strict
|
||||
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"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatiser avec un hook Gitea (optionnel)
|
||||
## Déploiement automatique par webhook
|
||||
|
||||
Pour que le déploiement se déclenche automatiquement à chaque fusion de pull request, configurez un **webhook** dans Gitea.
|
||||
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.
|
||||
|
||||
### Côté serveur : créer un endpoint HTTP minimal
|
||||
```
|
||||
push sur main → webhook Gitea → service d'écoute (local au serveur) → deploy-wiki.sh
|
||||
```
|
||||
|
||||
Installez un petit serveur de webhook (ex. [`webhook`](https://github.com/adnanh/webhook)) :
|
||||
Le service d'écoute est un petit serveur HTTP lancé par systemd, accessible uniquement
|
||||
depuis le serveur lui-même. Il vérifie la signature HMAC envoyée par Gitea (en-tête
|
||||
`X-Gitea-Signature`, secret partagé) avant de lancer quoi que ce soit, et ignore les
|
||||
push qui ne visent pas `main`.
|
||||
|
||||
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
|
||||
sudo apt install webhook
|
||||
tail -20 /var/log/wiki-deploy.log
|
||||
```
|
||||
|
||||
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.
|
||||
Une exécution réussie encadre le build par une ligne `Deploy started` et une ligne
|
||||
`Deploy done`.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue