Ikiwiki est un compilateur de wiki. Il prend un ensemble de pages de wiki pour les transformer en pages HTML prêtes à être publiées sur le Web. Les fichiers sources sont stockés avec un gestionnaire de versions tel que Git. Cela permet de modifier le site par l'intermédiaire soit d'une interface web, soit du gestionnaire de versions.
Avec un gestionnaire de versions décentralisé tel que Git, cela permet de garder aussi l'intégralité du contenu sur son ordinateur. Cette dernière capacité le rend particulièrement adapté pour constituer la base documentaire d'une équipe d'admin. sys. : on a encore les informations pour réparer sur son ordi quand le réseau ou les serveurs sont cassés.
Ce wiki utilisant Ikiwiki, la documentation côté user y est incluse.
Machines
Ikiwiki est actuellement installé sur bulbe.nos-oignons.net.
Fichiers
Configuration
/etc/ikiwiki/*.setup- Chaque fichier
.setupcorrespond à un wiki. Ils sont au format YAML. /etc/ikiwiki/wikilist- Contient la liste des wiki. Il est important de tenir cette liste à jour car elle indique la liste des wiki qu'il faut reconstruire lorsque le paquet Debian est mis à jour.
/etc/nginx/sites-available/*- Les sites gérés par Ikiwki étant accessibles à travers le web, la configuration des accès se fait avec Nginx.
Données
Chaque wiki dispose de son propre user système, dont le nom commence par
wiki-. Chaque wiki dispose de son propre répertoire dans /srv/ikiwiki, et
ce dernier contient :
/srv/ikiwiki/wiki-WIKI/.ssh/id_rsaetid_rsa.pub- Paire de clés SSH permettant d'accéder au dépôt Git contenant les sources du wiki.
/srv/ikiwiki/wiki-WIKI/src- Clone du dépôt Git. Utilisé par Ikiwiki pour compiler la version web et
pour enregistrer les modifications réalisées par l'interface web.
Il doit être nettoyé mensuellement avecgit-gc. /srv/ikiwiki/wiki-WIKI/dest- Site web compilé. Ce répertoire est accédé par Nginx pour servir le site.
/srv/ikiwiki/wiki-WIKI/ikiwiki.setup- Lien symbolique vers le fichier de configuration du wiki.
/srv/ikiwiki/wiki-WIKI/passwd- Lien symbolique vers la base d'authentification d'accès au wiki, s'il y en a une.
Mode d'interaction avec Git
Ikiwiki peut être configuré pour interagir avec Git de plusieurs manières.
Les sources d'un wiki sont stockées dans un dépôt Git central que les personnes autorisées clonent ou mettent à jour. Dans tous les cas, Ikiwiki dispose de son propre clone de ce dépôt central. C'est comme ça qu'il accède aux sources pour construire le site (en HTML). C'est également dans ce clone que seront enregistrées les modifications faites par l'interface web (avant d'être poussées vers le dépôt central).
Dans notre cas, on gère les dépôts centraux avec Gitolite. Pour que l'intégration soit plus simple et pour une meilleure séparation des privilèges, Ikiwiki accèdera au dépôt central par le même mécanisme que le reste du monde : via SSH. On utilisera le plugin pingee pour l'avertir lorsque des modifications ont lieu dans le dépôt central.
Pour chacun des wikis, on aura donc une paire de clés SSH permettant d'accéder en lecture et en écriture au dépôt Git central.
Lorsque des modifications sont poussées dans ce dépôt Git central, un post-commit hook s'occupera d'envoyer un ping à l'interface web d'Ikiwiki. Cela déclenchera la mise à jour du site.
Disposition spéciale pour le site web
Le site web de Nos oignons utilise également Ikiwiki. L'installation est néanmoins un peu particulière, vu qu'on utilise Ikiwiki comme un pur compilateur et pas comme un wiki qu'on modifie par le web.
Absence du CGI
Aucune interaction avec les personnes visitant le site n'est prévu. On laisse
donc les options cgiurl et cgi_wrapper vide.
Cela nous empêche par contre d'utiliser le plugin pingee comme on le fait
pour les autres installations. On va donc renseigner l'option git_wrapper et
exécuter ce hook lorsque des informations sont poussées vers le dépôt
central.
Deuxième instance d'Ikiwiki pour les modifications par le web
Afin de permettre aux personnes qui le souhaitent de modifier le site via une interface web plutôt que par Git, une deuxième instance d'Ikiwiki pointe sur le même dépôt Git central. Cette dernière contient le CGI et est en fait installée sur le même modèle que les autres wiki.
Mise à disposition d'une copie publique du dépôt
Dans le cas du site web, on met en place une copie publique du dépôt. Cela simplifie la vie des personnes extérieures qui souhaiteraient contribuer.
Pour ce faire, on modifie le post-update hook du dépôt Git central afin
qu'il s'occupe aussi de rafraîchir le dépôt public, via un git push --all.
Il ne faut pas non plus oublier d'activer le post-update hook dans le dépôt
public pour démarrer git update-server-info, vu que ce dernier est accédé en
HTTPS.
Informations pour la barre de trésorerie
Afin de pouvoir mettre à jour les informations liées à la trésorerie utilisées dans la page “Donnez” sans avoir besoin de manipuler Git, on met en place un underlay.
On a dans /srv/association/compta/underlay-website (en lien symbolique depuis
/srv/ikiwiki/website/underlay-compta) des fichiers qui
seront « intégrés » dans les sources du site sans pour autant être
présents dans le dépôt Git. Cela afin que le dossier puisse être mise à jour
via SFTP par le groupe compta.
Quand l'un des fichiers de ce dossier est mis à jour, il est nécessaire de
recompiler le site web. C'est systemd qui va s'occuper de surveiller
les changements via
/etc/systemd/system/update-website-on-underlay-changes.path afin
d'exécuter /etc/systemd/system/update-website-on-underlay-changes.service.
Ces fichiers sont :
data/budget-current.mdwn: un nombre entier d'euros, sans l'unité. C'est la somme des actifs, de ce qui est dû à l'association, moins les capitaux de provisions.data/budget-total.mdwn: un nombre entier d'euros, sans l'unité. C'est la somme des produits et des charges prévus d'ici un an.pourcentage-budget.mdwn: c'est le pourcentage des deux valeurs précédente (avec un '%' à la fin).
Ils sont inclus dans le code de la page via une directive
inline avec
raw="yes".
Disposition spéciale pour le wiki de l'admin sys.
Ce wiki utilise également Ikiwiki, mais son installation est particulière : on a deux instances, une publique et une privée.
L'instance publique est définie dans wiki-admin.setup, et exposée sur
https://nos-oignons.net/wiki-admin/. L'instance privée utilise
wiki-admin-ecrire.setup et /wiki-admin/ecrire/, par analogie avec le site.
Absence du CGI
Aucune interaction avec l'instance publique n'est prévue. On laisse
donc les options cgiurl et cgi_wrapper vide dans wiki-admin.setup.
Cela nous empêche par contre d'utiliser le plugin pingee comme on le fait
pour les autres installations. On va donc renseigner l'option git_wrapper et
exécuter ce hook lorsque des informations sont poussées vers le dépôt
central, comme pour le site web.
Partie privée
Une partie du site (toutes les pages commençant par Privé) sont exclues de la version publique.
exclude: ^(\.keyringer|Privé)
NOTE : L'exclusion de .keyringer n'est a priori pas nécessaire (c'est un
dotfile, donc ikiwiki ne compile/copie pas), mais la prudence ne nuit pas.
Disposition spéciale pour le wiki du conseil d'administration
Le wiki du conseil d'administration contient la base des adhésions. Cela entraîne quelques tweaks.
Gestion du YAML
Pour présenter les informations joliment, on a besoin de plugins supplémentaires pour gérer des informations au format YAML. Ces derniers ont été développés par Kathryn Andersen et n'ont pas encore été intégré au cœur d'Ikiwiki.
Pour les utiliser, on a donc mis en place un clone du dépôt ikiplugins qui se
trouve dans /srv/ikiwiki/wiki-ca/ikiplugins. Pour demander à Ikiwiki de les
utiliser, on met ce chemin dans l'option de configuration libdir.
Hooks Git
Afin d'éviter de mettre des informations non conformes dans la base, deux hooks Git empêchent de faire des erreurs.
Au niveau du dépôt central, un pre-receive hook empêche d'accepter des
mauvais changements envoyés dans la base adhérents par un push. Il doit être configuré dans
le dépôt central du wiki du C.A. (via un lien symbolique dans .git/hooks/pre-receive).
Au niveau du clone d'Ikiwiki (src), un pre-commit hook empêche
d'enregistrer de mauvais changements. Il est un peu bourrin, car il fait
également un git reset --hard dans ce cas, et perd donc complètement les
modifications… Il est nécessaire de le configurer à chaque fois qu'on clone le dépôt du wiki du
C.A. (en faisant un lien symbolique dans .git/hooks/pre-commit).
Il est arrivé que ces scripts ne fontionnent plus, probablement à cause d’une mise à jour du système de Bulbe. Bundler était cassé également. Un sudo gem install bundler && bundle install a résolu la situation.
Prévenir des modifications des dernières 24h
Pour prévenir des modifications ayant eu lieu pendant les dernières 24h, on va configurer l'appel dans script via cron depuis le compte du wiki.
Le script se trouve dans /usr/local/bin/mail-wiki-changes-for-yesterday.
Son appel est donc mis en place en modifiant le crontab du compta via la commande
crontab -u wiki-$WIKI -e.
Vu que le script utilise GnuPG pour chiffrer les messages, il est important de bien ajouter la clé correspondant à l'adresse d'admin dans le trousseau du compte.