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 .setup correspond à 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_rsa et id_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 avec git-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 par un push.

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…

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.

Procédures