Remplacer PlantUML par Kroki ?

Avant tout, un peu de mise en contexte ...

Vous savez sans doute que j'écris maintenant tous mes documents avec Asciidoc. Et comme je fais un travail assez technique, je dois régulièrement illustrer mon texte de diagrammes divers et variés. Et pour ça, j'utilise autant que possible PlantUML. Et dans la plupart des cas c'est très cool. Mais dans les cas où ça ne marche pas ... eh bien ça ne marche pas, et je me retrouve bien embêté.

Par exemple, pour faire les graphiques qu'on trouve dans toutes les présentations de manager, on peut facilement utiliser vega grâce à asciidoctor-diagram ! Sauf que vega, en tant que librairie Javascript, a des dépendances ... exotiques. En effet, vega-cli tire directement canvas, qui s'installe très difficilement sous Windows. Entre gyp qui vous oblige à télécharger Python 2, et GTK, c'est vraiment la fête. Et autant dans Asciidoc on peut utiliser une instance externe de PlantUML (ce que je fais systématiquement grâce à Docker), autant on ne peut pas utiliser d'instance externe de vega . Correction : en cherchant comment configurer asciidoctor-diagram pour utiliser une instance PlantUML externe, je viens de découvrir qu'en fait, ça n'est pas possible dans asciidoctor-diagram (parce qu'il utilise naturellement une instance embarquée du jar plantuml) mais uniquement dans la preview Asciidoc de VSCode.

Pour en revenir à vega, il est inutilisable sous Windows.

Et c'est là que Kroki entre en scène.

Kroki fournit tout un tas de librairies de diagram as code à travers une API unifiée. Et ces librairies sont aussi utilisables dans des images Docker (ce qui supprime les problèmes de vega). Hélas, il faut lancer toutes ces images avant de pouvoir utiliser asciidoctor-kroki.

Et la doc est claire : on peut lancer toutes ces images sans docker-compose (qui me fatigue un tout petit peu) du moment qu'on met les bonnes variables d'environnement.

Et l'avantage si je me passe de docker-compose, c'est que mon instance de watchtower maintiendra tout ça à jour (j'aurais pu aussi ajouter watchtower dans le fichier docker-compose.yml, mais je n'ai pas envie de me fatiguer).

Allons-y donc !

D'abord, installer les images Docker des librairies externes (dans mon cas, excalidraw, parce que les autres font partie de l'installation standard - ce qui peut être embêtant, si kroki met à jour ses dépendances "trop lentement")

docker run --name kroki-excalidraw --restart=always -p 29004:8004 yuzutech/kroki-excalidraw

Et ensuite, installer l'image Docker kroki avec plusieurs subtilités que j'expliquerai par la suite

docker run --name kroki --restart=always -p 29000:8000 -e KROKI_EXCALIDRAW_HOST=kroki-excalidraw -e KROKI_SAFE_MODE=unsafe -e KROKI_PLANTUML_ALLOW_INCLUDE=true yuzutech/kroki

Donc comme j'ai lancé kroki-excalidraw à part, il faut indiquer quelle machine gèrera les diagrammes excalidraw (d'où KROKI_EXCALIDRAW_HOST). Et les autres variables d'environnement devraient me permettre de continuer à utiliser des includes dans mes diagrammes PlantUML, ce que je fais ... beaucoup.

Et paf, ça marche !

Reste maintenant à faire marcher tout ça dans mes documents Asciidoc avec asciidoctor-kroki. Ce qui n'est pas si compliqué, puisque j'ai bien l'impression que c'est la même syntaxe qu'asciidoctor-diagram.

Installer un gem dans un build Java n'est pas si simple, heureusement, je l'ai déja fait! Reste maintenant à tester ça, par exemple avec un diagramme excalidraw ?