Description

Gollum est un service simple de Wiki, synchronisé via Git, et pouvant traiter divers langage de Markup, dont Markdown ou Org-mode. Il s'agit du service par défaut utilisé par les wikis Gitlab et Github, mais il peut aussi être autohébergé seul, comme fait au ResEl.

Motivations

Avant, le ResEl a utilisé trac puis redmine comme solution complète de gestion de projet. Mais il a été décidé, suite au passage à Gitlab comme solution de gestion de projet, de séparer les outils de gestion de projet et le wiki.

Mise en place

Gollum est un programme développé en Ruby, qui se compose de trois parties, le frontend Gollum, le backend Gollum-lib et l'interface avec git rugged-adapter.

Gollum a été mis en place sur Smeagol, il pousse une plateforme web https://wiki.resel.fr, pointant sur le reverse publique Situs.

Pour résoudre quelques problèmes dans Gollum (notamment d'UTF-8), le code a été légèrement patché par le ResEl, le code est disponible sur le dépôt associé, plus d'informations sur le README.

Le wiki est disponible sur le dépôt ResEl/general.wiki et est synchronisé avec le dépôt sur Smeagol dans /home/wiki/general.wiki.

Utilisation

A priori, vous avez réussi à vous connecter et naviguer jusqu'à cette page, Bravo clap !

Rédaction des articles

Pour rédiger un article, vous pouvez simplement cliquer sur le lien vers un article inexistant, ou cliquer sur le bouton New. Pour éditer, le bouton Edit.

La rédaction peut se faire selon différents langages de markup, le recommandé étant Markdown, lisez le tuto.

Quelques conseils
  • Pour un service et la machine qui l'héberge :
    Tout ce qui touche au serice va sur la page service, tout ce qui touche à la machine va sur la page machine. On évite de mélanger des infos. Il faut bien comprendre qu'une machine peut être supprimé, et le service réinstallé sur une autre. Donc sur la page de la machine on ne traite que des infos du service vraiment en rapport avec la machine.
    Quelques pages modèles : Gollum/Smeagol, Sites Clubs/Golf
Markup avancé

On peut faire des trucs comme ça :

{{{{{{ blue-modern alice->bob: Test bob->alice: Test response }}}}}}

{{{{{{ blue-modern
    alice->bob: Test
    bob->alice: Test response
}}}}}}

ou comme ça :

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml

Plus de détails sur la doc officielle.

Configuration

Techniquement, gollum est fait pour gérer en même temps plusieurs wiki. Aussi il y a une configuration globale, et une configuration spécifique au wiki.

Actuellement, le seul wiki géré est celui Général, mais cela peut-être étendu simplement.

Globale

warning La configuration fait l'objet d'un versionnage sur le dépôt git.

La configuration principale est directement dans le fichier unit de Gollum, passant directement les arguments au lancement. Dans /etc/systemd/system/gollum.service. Extrait intéressant : 

ExecStart=/usr/local/bin/bundle exec bin/gollum --show-all --emoji --adapter rugged "/home/wiki/general.wiki" --css
Il est précisé au lancement d'utiliser les emojis, l'interface git rugged qui est meilleure que celle par défaut au niveau de la gestion de l'utf-8, l'emplacement du dossier wiki (c'est ici qu'il faut indiquer de nouveaux chemins pour gérer plus de Wikis), et le switch css indique à Gollum d'injecter une feuille de style customisée par projet.

Pour soucis de préserver un versionnage propre du code, modifier la configuration sur le dépôt.

Allez voir les détails de mise en place de Gollum sur Sméagol pour voir comment est installé le service et comment puller des modifications.

Par wiki

warning Ces fichiers de customisation sont directement versionné sur le dépôt du wiki.

Comme indiqué, on peut utiliser les switches css ou js pour indiquer à Gollum de charger, respectivement, une feuille de style, ou un ensemble de script, customisés, pour un wiki.

Gollum va chercher dans le dossier du wiki un fichier custom.css et un fichier custom.js si les switches sont activés, et les charge.

Ça permet de customiser l'apparence de Gollum.

Lien utiles

Listes de lien utiles, dans l'ordre :

Historique

  • Mise en place initiale par Théo Jacquin en 2017