Du docker-compose au diagramme : l’histoire de compose-diagrams

Un problème que tout le monde a déjà vu

Ouvrez un article technique sur un système distribué et cherchez le diagramme d’architecture. Il est presque toujours là : des boîtes, des flèches, un cylindre pour la base de données. Et il a presque toujours été dessiné à la main, dans un outil de dessin générique, avec une notation que seul son auteur connaît.

L’outil que je présente ici est né d’une discussion dans un cours de mon doctorat. Nous sommes partis d’un constat : les praticiens utilisent le plus souvent des diagrammes informels pour représenter les composants d’un système. Des notations comme UML apparaissent surtout dans les travaux universitaires ou dans les documents qui formalisent des modèles logiciels, et le modèle C4, moins formel, gagne du terrain chez les praticiens. Au quotidien, pourtant, c’est le diagramme ad hoc qui domine.

Le diagramme ad hoc a deux défauts. Il ne suit aucune règle, si bien que chaque lecteur doit deviner ce que signifie une flèche. Et il vieillit : le système change, le dessin reste, et au bout d’un moment les deux ne racontent plus la même histoire.

L’idée : le système se décrit déjà lui-même

La piste qui est sortie de cette discussion consistait à arrêter de dessiner et à commencer à générer. Un système distribué moderne est déjà accompagné d’artefacts qui décrivent son déploiement. Un fichier docker-compose.yaml indique quels services existent, quelle image chacun exécute, quels ports il publie, de quoi il dépend et où il stocke ses données.

Nous appelons ces artefacts des descripteurs de système. Ils ont une qualité qu’aucun dessin ne possède : ils servent réellement à démarrer le système, donc ils ne peuvent pas devenir obsolètes sans que quelqu’un s’en aperçoive.

Un diagramme généré à partir du descripteur hérite de cette qualité. Le fichier change, le diagramme change avec lui. La cohérence ne dépend plus de la discipline de la personne qui dessine.

Du prototype à l’article

Nous avons lancé le projet en juin 2020. C’était alors un prototype en Python appelé DAD, pour Descriptor to Architectural Diagrams : une preuve de concept destinée à montrer qu’il était possible de générer un diagramme d’architecture à partir d’un fichier docker-compose. Il lisait le fichier et dessinait les services, les dépendances et les volumes avec Diagrams, une bibliothèque qui crée des diagrammes à partir de code. Montrer que c’était faisable n’était toutefois qu’une première étape. La question qui nous intéressait était ailleurs : un diagramme généré à partir du descripteur de système est-il plus cohérent avec le système qu’un diagramme ad hoc ?

En 2021, cette question est devenue un article. Nous avons publié Towards improving architectural diagram consistency using system descriptors à la 29th IEEE/ACM International Conference on Program Comprehension (ICPC 2021). Une prépublication est disponible sur arXiv.

L’article avance deux hypothèses : un diagramme généré à partir d’un descripteur valide est cohérent, et un descripteur valide généré à partir d’un diagramme l’est aussi. Dans l’étude de cas, nous avons écrit un descripteur à partir du diagramme de déploiement de Netflix, puis généré un nouveau diagramme. Tous les éléments du fichier docker-compose ont pu être représentés, et le diagramme généré ne présentait aucune des incohérences de l’original.

En 2022, nous avons poursuivi la recherche avec An approach to build consistent software architecture diagrams using DevOps system descriptors, paru dans les Companion Proceedings de l’ACM/IEEE 25th International Conference on Model Driven Engineering Languages and Systems (MODELS ’22). Ce second article propose des lignes directrices pour créer des diagrammes, une taxonomie des concepts présents dans les descripteurs de système et un processus pour transformer les descripteurs en diagrammes, appliqué à un système de fil d’actualité décrit en Docker Compose. Sa conclusion restait prudente : pour l’instant, les descripteurs ne mènent à des diagrammes cohérents que dans une certaine mesure, mais l’approche est prometteuse. Il est également disponible sur arXiv.

À cette époque, la recherche s’est tournée vers un sondage auprès de professionnels du génie logiciel. Nous leur avons montré quelques diagrammes d’architecture et les avons interrogés sur les forces et les faiblesses de ceux qui étaient générés à partir de descripteurs. Le code, lui, est resté à l’arrêt : le dernier commit de cette phase date de mai 2021.

La reprise : compose-diagrams

En 2026, j’ai repris le projet, désormais sous le nom compose-diagrams. Dans le prototype, le fichier d’entrée était inscrit en dur dans le code ; la version actuelle est un outil que chacun peut installer et utiliser. Elle apporte trois nouveautés.

Ligne de commande. Une commande reçoit le fichier docker-compose et renvoie l’image en PNG, SVG, PDF ou JPG, dans le sens de mise en page de votre choix.

Interface web locale. Une page avec le fichier à gauche et le diagramme à droite, redessiné au fil de vos modifications. Elle fonctionne sur votre machine, et le fichier n’est envoyé nulle part.

Style C4. C’est la nouveauté la plus proche de la discussion d’origine. En plus du diagramme à icônes, l’outil génère le diagramme de conteneurs du modèle C4 : le projet Compose est la frontière du système, chaque service est un conteneur avec son image et ses ports, les bases de données et les volumes nommés sont des magasins de données, et les dépendances deviennent des relations étiquetées. Le lecteur reçoit une notation qu’il connaît déjà, plutôt qu’un dessin ad hoc de plus.

Les deux figures ci-dessous proviennent du même fichier, un exemple avec MySQL, PostgreSQL, Kafka et Zookeeper.

Figure 1. Style ad hoc : services, dépendances et volumes représentés par des icônes

Figure 2. Style C4 : diagramme de conteneurs du même système

Comment l’essayer

Il vous faut Python 3.9 ou plus récent et Graphviz. Ensuite :

git clone https://github.com/jalvesnicacio/compose-diagrams.git
cd compose-diagrams
python3 -m venv .venv
source .venv/bin/activate
pip install .

Pour générer un diagramme à partir d’un fichier, dans le style ad hoc puis dans le style C4 :

compose-diagrams docker-compose.yaml
compose-diagrams docker-compose.yaml -s c4 -o architecture.svg

Pour ouvrir l’interface web dans le navigateur :

compose-diagrams --web

Le dépôt contient des fichiers d’exemple dans le dossier docker-compose-files, si vous voulez essayer avant d’utiliser l’un des vôtres.

Si vous préférez ne pas installer Python ni Graphviz, vous pouvez utiliser Docker. Depuis le dossier du projet, construisez l’image et lancez l’interface web, accessible à l’adresse http://localhost:8000 :

docker build -t compose-diagrams .
docker run --rm -p 8000:8000 compose-diagrams

La même image sert aussi de ligne de commande. Montez le dossier qui contient votre fichier, et le diagramme y est écrit :

docker run --rm -v "$PWD":/work compose-diagrams docker-compose.yaml -o diagramme.png

La suite

Le projet est libre et loin d’être terminé. Ce qui reste à faire est consigné dans les tickets sur GitHub, et certains sont de bons points d’entrée pour qui voudrait contribuer :

• les gros fichiers produisent encore des diagrammes beaucoup trop larges ;
• le style ad hoc utilise la même icône de serveur pour tout, alors qu’il pourrait afficher celle de MySQL, de Redis ou de Kafka;
• les réseaux du fichier docker-compose sont lus, mais pas encore dessinés;
• le paquet n’est pas sur PyPI et l’image Docker n’est dans aucun registre, si bien qu’il faut encore cloner le dépôt pour l’installer.

Il reste aussi des questions ouvertes sur le C4. Un fichier docker-compose ne dit ni qui utilise le système ni avec quels systèmes externes il communique, et ce sont des éléments centraux d’un diagramme C4. Comment les représenter sans inventer d’information : c’est une discussion que j’aimerais avoir avec celles et ceux qui utilisent cette notation au quotidien.

Le jour même de l’ouverture des tickets, deux contributions externes sont arrivées, de deux personnes différentes. La première est venue quelques minutes après le ticket qu’elle corrige, et les deux sont déjà intégrées au projet. Si les diagrammes dépassés vous dérangent aussi, le dépôt est ouvert.