fd3c8b41b4
La page supposait partout que le contributeur a les droits d'écriture sur le dépôt : l'option « créer une branche et ouvrir une pull request » de l'éditeur Gitea n'apparaît que dans ce cas, et la procédure locale poussait une branche directement sur le dépôt. Quelqu'un d'extérieur à l'équipe tombait sur une bifurcation sans savoir ce que c'était. Les deux parcours sont donc repris autour de la bifurcation, et la pull request est présentée comme la règle pour tout le monde, mainteneurs compris — avec la raison plutôt que l'injonction : relecture, trace des discussions, et le droit de laisser un texte reposer sans qu'il soit déjà en ligne. Le push direct est ramené à ce qu'il doit être, un geste d'urgence. La procédure locale gagne les étapes qui manquaient : remote upstream, mise à jour de main avant de créer une branche, build --strict avant de proposer. Et pour Obsidian, se placer sur sa branche avant d'écrire, puisque la sauvegarde automatique pousse sur la branche courante. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG
119 lines
4.8 KiB
Markdown
119 lines
4.8 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 | **Bifurquer**, cloner, 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 le clone comme coffre — il est déjà configuré — sur une branche | 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
|
|
fusionner une pull request : le contenu arrive sur `main`, le reste est automatique.
|
|
|
|
> **La pull request est la règle, pour tout le monde.** On ne modifie pas `main`
|
|
> directement, même quand on en a le droit : c'est ce qui permet la relecture, garde une
|
|
> trace des discussions, et laisse le temps à un texte de reposer avant d'être publié.
|
|
|
|
---
|
|
|
|
## 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 commit sur `main` est une publication.** Pas de relecture, pas d'étape de
|
|
> validation : le site est reconstruit dans la foulée. D'où la règle ci-dessus — les
|
|
> brouillons vivent sur une branche. Attention en particulier à la sauvegarde automatique
|
|
> d'Obsidian Git, qui commite et pousse toute seule sur la branche courante.
|
|
|
|
> **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`.
|