Alpinux dd60bacf54 Dire explicitement qui fait quoi pour publier

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

2026-09-19 22:32:56 +02:00

4.5 KiB

Raw Blame History

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
Écrire un article, travailler hors ligne	Cloner le dépôt, une branche par sujet, pull request	Rédiger 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

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

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 :

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.

4.5 KiB Raw Blame History