dd60bacf54
Le README annonçait « le push suffit » sans dire à qui cela s'adressait, et la page Contribuer décrivait une publication manuelle en 24 à 48 heures — ce qui n'a jamais correspondu au webhook, et plus du tout depuis qu'il fonctionne. README : un tableau « je veux… » qui relie chaque intention à son geste et à la page qui le détaille, le trajet d'un commit jusqu'à la mise en ligne, et les deux pièges — un push sur main publie sans relecture, et le webhook n'écoute que ce dépôt. contribuer.md : le délai réel (quelques secondes) et le filet du staging, plus une section « Rédiger depuis son ordinateur » — clone, aperçu local, branche et pull request, coffre Obsidian — qui n'était documentée nulle part alors que c'est la façon dont le wiki est rédigé au quotidien. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG
115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
# wiki.alpinux.org
|
|
|
|
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é **sur le serveur**, à chaque push sur `main`.
|
|
|
|
---
|
|
|
|
## Je veux…
|
|
|
|
| Ce que vous voulez faire | Ce que vous faites | Détail |
|
|
|---|---|---|
|
|
| Corriger une faute, mettre à jour une info | Éditer la page dans Gitea, ouvrir une **pull request** | [Contribuer](https://wiki.alpinux.org/contribuer/) |
|
|
| Écrire un article, travailler hors ligne | Cloner le dépôt, **une branche par sujet**, pull request | [Rédiger depuis son ordinateur](https://wiki.alpinux.org/contribuer/#rediger-depuis-son-ordinateur) |
|
|
| Rédiger dans Obsidian | Ouvrir ce dossier comme coffre — il est déjà configuré | idem |
|
|
| Relire et publier une contribution | Fusionner la pull request : la publication suit | ci-dessous |
|
|
| Comprendre pourquoi ça n'est pas en ligne | Lire le journal de déploiement sur le serveur | [Déploiement du wiki](https://wiki.alpinux.org/technique/deploiement-wiki/) |
|
|
|
|
**Personne n'a de build à lancer ni de fichier à copier sur le serveur.** Publier, c'est
|
|
faire arriver du contenu sur la branche `main` de ce dépôt — que ce soit par une pull
|
|
request fusionnée ou par un push direct.
|
|
|
|
---
|
|
|
|
## Ce qui se passe une fois sur `main`
|
|
|
|
```
|
|
main (Gitea)
|
|
│ webhook ──▶ service d'écoute sur le serveur (signature vérifiée)
|
|
▼
|
|
deploy-wiki.sh : git pull → mkdocs build --strict → staging
|
|
│
|
|
│ build réussi ? ── non ──▶ le site en ligne reste tel quel
|
|
▼ oui
|
|
rsync vers le DocumentRoot Apache ──▶ https://wiki.alpinux.org
|
|
```
|
|
|
|
Compter **une minute** entre le push et la page à jour. Le build passe par un répertoire
|
|
de staging : une erreur — lien mort, page absente de la navigation — laisse le site en
|
|
ligne intact plutôt que de le publier à moitié.
|
|
|
|
### Les deux pièges à connaître
|
|
|
|
> **Un push sur `main` est une publication.** Pas de relecture, pas d'étape de validation :
|
|
> le site est reconstruit dans la foulée. Les brouillons vont sur une branche. Cela vaut
|
|
> aussi pour la sauvegarde automatique d'Obsidian Git, qui commite et pousse toute seule.
|
|
|
|
> **Le webhook est attaché à ce dépôt.** Un push dans l'ancien monorepo
|
|
> `alpinux.site.2026`, qui a longtemps hébergé le wiki, ne publie plus rien.
|
|
|
|
---
|
|
|
|
## Structure des sources
|
|
|
|
```
|
|
.
|
|
├── mkdocs.yml # Configuration MkDocs (nav, thème, plugins)
|
|
├── docs/ # Pages Markdown
|
|
│ ├── index.md
|
|
│ ├── alpinux/ # Présentation, FAQ, événements
|
|
│ ├── guides/ # Guides pratiques (Linux Mint, Docker, chiffrement…)
|
|
│ ├── presentations/ # Supports de présentations passées
|
|
│ ├── technique/ # Documentation technique (déploiement, serveur…)
|
|
│ └── communication/
|
|
├── 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 (build-assets.py)
|
|
└── .obsidian/ # Réglages du coffre Obsidian (partagés)
|
|
```
|
|
|
|
Aucune image n'est versionnée ici : le logo et les illustrations sont servis depuis
|
|
`static.alpinux.org`, les pages y pointent par leur URL complète. `scripts/build-assets.py`
|
|
sert à fabriquer les fichiers du logo à y téléverser quand le SVG source change — il ne
|
|
tourne pas au déploiement.
|
|
|
|
---
|
|
|
|
## Développement local
|
|
|
|
```bash
|
|
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) avant de pousser :
|
|
|
|
```bash
|
|
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)
|
|
|
|
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 un déploiement
|
|
|
|
---
|
|
|
|
## Voir aussi
|
|
|
|
Ce dépôt se suffit à lui-même : `~/Projects/alpinux.wiki`, rien à cloner à côté.
|
|
|
|
Pour les autres projets de l'association (les applications Flask, le CDN, l'infra) et
|
|
leurs procédures de déploiement : `~/Projects/org.alpinux.owni/README.md`.
|