Héberger Kroki sur un VPS infogéré, c'est rendre vos diagrammes PlantUML, Mermaid, GraphViz, D2, BPMN ou Excalidraw sur une machine à vous, que nos équipes tiennent à jour et supervisent jour et nuit. Kroki est un logiciel libre sous licence MIT. Ce guide suit sa documentation officielle : la passerelle et ses conteneurs compagnons, l'installation avec Docker Compose, la configuration, HTTPS, la protection d'une instance publique, le branchement d'Asciidoctor et de MkDocs, les sauvegardes et les mises à jour.
Par Simon Vasconcelos Lee
Publié le 20 novembre 2026Lecture : 15 minutes
yuzutech/kroki.KROKI_*_HOST : Docker Compose les démarre ensemble.SECURE, qui l'empêche de lire des fichiers ou le réseau ; l'accès à une instance publique se règle au proxy inverse.compose.yaml et celle du proxy, puis mettez à jour avec docker compose pull en lisant chaque note de version.Kroki fournit une API HTTP unifiée qui prend un diagramme décrit en texte et renvoie une image. Votre documentation, votre wiki ou votre forge envoient la source du diagramme ; Kroki répond avec un SVG, et selon le type de diagramme un PNG, un PDF ou un JPEG. Son README cite BlockDiag, BPMN, Bytefield, C4 avec PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom et WireViz.
/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000. Une page web l'affiche alors comme n'importe quelle image./graphviz/svg, ou dans le corps JSON.Kroki-Diagram-Options-*.La documentation de l'extension Asciidoctor Kroki donne trois raisons d'avoir son propre serveur plutôt que l'instance publique kroki.io : un pare-feu d'entreprise qui ne la laisse pas passer, la latence quand on est loin de cette instance européenne, et la confidentialité, quand la source des diagrammes ne doit pas quitter votre infrastructure.
Kroki est publié sous licence MIT. Elle accorde gratuitement le droit d'utiliser, de copier, de modifier, de fusionner, de publier, de distribuer, de sous-licencier et de vendre des copies du logiciel. Vous pouvez donc le faire tourner pour votre entreprise, votre équipe ou vos clients, sans licence à acheter.
La seule condition est de garder la notice de copyright et le texte de la licence dans toute copie ou partie substantielle du logiciel. Le texte fournit le logiciel « tel quel », sans garantie. Les bibliothèques de diagrammes que Kroki embarque gardent chacune leur propre licence.
Kroki a une architecture modulaire. Une passerelle écrite en Java, sur Vert.x, reçoit toutes les requêtes et les oriente vers la bonne bibliothèque. Seule l'image yuzutech/kroki est obligatoire : la documentation précise que, selon vos diagrammes, elle peut suffire.
| Image | Ce qu’elle rend | Obligatoire |
|---|---|---|
yuzutech/kroki | La passerelle, et ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML et C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom et WireViz | Oui |
yuzutech/kroki-mermaid | Mermaid : diagrammes de flux, de séquence et de Gantt | Non |
yuzutech/kroki-bpmn | BPMN, avec bpmn-js | Non |
yuzutech/kroki-excalidraw | Excalidraw, le style dessiné à la main | Non |
yuzutech/kroki-diagramsnet | diagrams.net, encore expérimental | Non |
La documentation ne chiffre ni la mémoire ni le processeur. Elle donne en revanche ce qui pèse : les compagnons Mermaid, BPMN, Excalidraw et diagrams.net rendent chaque diagramme dans un navigateur Chromium sans interface. Pour qu'une rafale de conversions ne dépasse pas la mémoire du conteneur, chacun limite ses rendus simultanés : 6 par défaut pour Mermaid, BPMN et diagrams.net, 4 pour Excalidraw. Les requêtes suivantes attendent leur tour dans une file.
yuzutech/kroki 0.36.0 pèse environ 1 Go compressée. Kroki n'écrit pas de données : il ne garde rien entre deux requêtes.amd64 et arm64.depends_on et KROKI_*_HOST.Sur un VPS infogéré, décrivez-nous vos diagrammes, les compagnons qu'ils demandent et le trafic attendu, et nous vous recommandons la taille qui convient.
La documentation recommande les conteneurs, Docker ou Podman, pour ne pas installer chaque bibliothèque à la main. Sur un serveur où Docker est installé, créez un dossier et placez-y ce compose.yaml, tiré de la documentation :
services:
kroki:
image: yuzutech/kroki:0.36.0
restart: unless-stopped
depends_on:
- mermaid
- bpmn
- excalidraw
environment:
- KROKI_MERMAID_HOST=mermaid
- KROKI_BPMN_HOST=bpmn
- KROKI_EXCALIDRAW_HOST=excalidraw
ports:
- "127.0.0.1:8000:8000"
# Si vous montez /tmp vous-même, gardez l'option exec
tmpfs:
- /tmp:exec
mermaid:
image: yuzutech/kroki-mermaid:0.36.0
restart: unless-stopped
expose:
- "8002"
bpmn:
image: yuzutech/kroki-bpmn:0.36.0
restart: unless-stopped
expose:
- "8003"
excalidraw:
image: yuzutech/kroki-excalidraw:0.36.0
restart: unless-stopped
expose:
- "8004"
docker compose up -d
127.0.0.1 : c'est le premier écart avec l'exemple de la documentation, qui publie 8000:8000. Kroki écoute sur toutes les interfaces par défaut, et Docker publie un port sur toutes les adresses du serveur s'il n'en reçoit aucune. Ici, l'API ne s'atteint que par le proxy inverse.expose : il reste sur le réseau interne de Compose, où la passerelle les joint par leur nom de service. Les variables KROKI_MERMAID_HOST, KROKI_BPMN_HOST et KROKI_EXCALIDRAW_HOST donnent ce nom ; leurs ports par défaut, 8002, 8003 et 8004, n'ont pas à être répétés.0.36.0 est le second écart : l'exemple de la documentation suit la dernière version. Les quatre images sont publiées ensemble sous la même étiquette, ce qui fixe une version cohérente et rend chaque mise à jour volontaire.Pour diagrams.net, encore expérimental, le README ajoute un quatrième compagnon. Ajoutez ce service et la variable KROKI_DIAGRAMSNET_HOST=diagramsnet dans l'environment de kroki :
diagramsnet:
image: yuzutech/kroki-diagramsnet:0.36.0
restart: unless-stopped
expose:
- "8005"
Depuis le serveur, la route /health renvoie l'état de la passerelle et les versions des bibliothèques qu'elle embarque. Les deux requêtes suivantes rendent un diagramme GraphViz par la passerelle, puis un diagramme Mermaid par son compagnon :
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/graphviz/svg --data-raw 'digraph G {Hello->World}'
curl http://127.0.0.1:8000/mermaid/svg --data-raw 'graph TD; A-->B'
L'autre voie de la documentation est le serveur autonome, publié sur la page des versions du dépôt sous le nom kroki-standalone-server-v0.36.0.jar. Il demande Java 21 ou plus récent, et il ne contient aucune bibliothèque de diagrammes : chacune s'installe à part, et son chemin se donne par une variable comme KROKI_DOT_BIN_PATH quand l'exécutable n'est pas dans le PATH. Pour l'écoute, préférez KROKI_LISTEN, car la documentation de configuration annonce le retrait de KROKI_PORT :
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar
Kroki n'a pas de page d'administration, pas de comptes utilisateurs et pas de base de données : sa configuration tient en variables d'environnement, ou en propriétés système Java avec le jar. Dans Docker Compose, elles se placent dans le bloc environment du service concerné, puis docker compose up -d recrée le conteneur. Les réglages qui comptent le plus pour un serveur :
| Variable | Défaut | Son rôle |
|---|---|---|
KROKI_SAFE_MODE | secure | Le niveau de sécurité, détaillé plus bas |
KROKI_LISTEN | Toutes les interfaces, port 8000 | L’adresse et le port d’écoute ; accepte aussi un socket UNIX, unix:// et un chemin |
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST | 127.0.0.1 | Où la passerelle joint chaque compagnon ; les variables _PORT correspondantes donnent le port, et KROKI_DIAGRAMSNET_HOST sert à diagrams.net |
KROKI_COMMAND_TIMEOUT | 5 secondes | L’attente maximale d’un exécutable de diagramme, comme dot |
KROKI_CONVERT_TIMEOUT | 20 secondes | L’attente maximale d’une bibliothèque Java, comme PlantUML |
KROKI_DELEGATE_TIMEOUT_MS | 30 000 | L’attente maximale d’un compagnon, en millisecondes |
KROKI_MAX_URI_LENGTH | 4 096 | La longueur d’adresse acceptée en GET, au-delà de laquelle Kroki répond 414 |
KROKI_CONTENT_SECURITY_POLICY | script-src 'none'; object-src 'none' | L’en-tête Content-Security-Policy envoyé avec chaque réponse |
KROKI_CORS_ALLOWED_HEADERS | Aucun en plus | Les en-têtes supplémentaires permis aux appels d’un autre site |
Les diagrammes Excalidraw produisent de longues adresses. Si vous montez KROKI_MAX_URI_LENGTH, la documentation recommande de ne pas dépasser 8 192 caractères, bien que la plupart des navigateurs acceptent davantage dans une balise <img>. Pour les plus gros diagrammes, une requête POST transporte la source dans le corps plutôt que dans l'adresse.
Kroki ne demande aucun secret pour fonctionner. Deux réglages facultatifs en portent un : le jeton KROKI_COMPANION_REGISTRATION_TOKEN, utile si vous activez l'enregistrement de compagnons tiers, présenté dans la section sur la protection, et la clé privée d'un certificat, si vous confiez HTTPS à Kroki lui-même. Gardez-les hors de tout dépôt de code.
La passerelle sert l'API en HTTP. Un proxy inverse placé devant elle écoute sur les ports 80 et 443, obtient le certificat Let's Encrypt, chiffre le trafic et transmet à Kroki sur 127.0.0.1:8000. C'est aussi lui qui filtre l'accès, comme le montre la section suivante.
Caddy obtient et renouvelle seul le certificat du nom indiqué, et sa directive reverse_proxy transmet les en-têtes X-Forwarded-For, X-Forwarded-Proto et X-Forwarded-Host sans réglage :
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
Ce bloc de site écoute sur le port 80 pour laisser Certbot installer HTTPS. Deux limites de Nginx croisent celles de Kroki : un corps de requête au-delà de 1 Mo est refusé par défaut, avec un 413, ce que règle client_max_body_size pour les gros diagrammes envoyés en POST ; une ligne de requête plus longue que 8 Ko reçoit un 414, ce que règle large_client_header_buffers si vous montez KROKI_MAX_URI_LENGTH au-delà.
server {
listen 80;
listen [::]:80;
server_name diagrams.example.com;
client_max_body_size 1m;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:8000;
}
}
sudo nginx -t
sudo certbot --nginx
La documentation décrit aussi un chiffrement par Kroki lui-même : KROKI_SSL=true, avec le certificat et la clé privée au format PEM, en texte par KROKI_SSL_CERT et KROKI_SSL_KEY, ou en fichiers par KROKI_SSL_CERT_PATH et KROKI_SSL_KEY_PATH. Le renouvellement du certificat se fait ici à la main, alors que Caddy ou Certbot s'en chargent seuls devant un proxy.
Kroki n'a pas d'authentification : quiconque atteint l'API peut lui faire rendre des diagrammes. Sa protection repose donc sur trois choses, que la documentation et les notes de version décrivent : le mode de sécurité, les limites de taille et de temps, et ce que le proxy laisse passer. Commencez par savoir qui doit atteindre votre serveur.
kroki-fetch-diagram, le plugin MkDocs avec http_method: POST : les images sont enregistrées avec le site, et le serveur Kroki n'a plus besoin d'être public.KROKI_SAFE_MODE fixe trois niveaux, chacun reprenant les restrictions du précédent. La documentation explique que certaines bibliothèques savent lire des fichiers ou des adresses, comme les directives !include de PlantUML, et que Kroki, faute de relire leur code, bloque ces accès par défaut. Elle invite chaque exploitant à choisir le niveau qui convient à son usage.
| Niveau | Ce qu’il fait |
|---|---|
SECURE, par défaut | Bloque toute tentative de lire des fichiers du système ou des ressources du réseau |
SAFE | S’en remet à l’assainissement des requêtes fait par le mode sécurisé de chaque bibliothèque |
UNSAFE | Désactive toutes les protections |
SECURE, ses !include et !includeurl sont refusés, et son profil de sécurité est SANDBOX. En SAFE, le profil devient ALLOWLIST, et KROKI_PLANTUML_ALLOWLIST_URL ou KROKI_PLANTUML_ALLOWLIST_PATH désignent ce qui peut être inclus.UNSAFE, leur navigateur ne charge que des ressources locales. Pour autoriser une banque d'images interne sans quitter ce mode, la documentation propose KROKI_ALLOWED_ORIGINS, ou sa variante par compagnon comme KROKI_MERMAID_ALLOWED_ORIGINS, sur le conteneur compagnon.UNSAFE : ni !include pour Structurizr, ni image externe pour BlockDiag, ni lecture de fichier pour Lini.KROKI_STRUCTURIZR_SAFE_MODE ou KROKI_MERMAID_SAFE_MODE, plutôt que d'abaisser tout le serveur.Sur une instance publique, gardez SECURE. L'en-tête Content-Security-Policy, envoyé par défaut depuis la 0.36.0, complète cette défense : un script glissé dans un SVG ne s'exécute pas sur l'origine de Kroki, même si l'image est ouverte directement.
Les délais du tableau de configuration bornent chaque conversion. Les compagnons ajoutent les leurs, pensés contre l'épuisement des ressources :
KROKI_MERMAID_MAX_TEXT_SIZE) ou de plus de 500 liens, avec un 400, et abandonne un rendu au-delà de 10 secondes, avec un 408. Ces limites ne se contournent pas par les paramètres d'une requête.KROKI_MAX_BODY_SIZE).Quand seule votre chaîne de publication appelle Kroki, le plus simple est de n'accepter que son adresse IP. Avec Caddy, le filtre remote_ip repère les autres adresses, et respond leur renvoie un 403 :
diagrams.example.com {
@externe not remote_ip 203.0.113.10
respond @externe 403
reverse_proxy 127.0.0.1:8000
}
Avec Nginx, les directives allow et deny du bloc location font le même travail, la première règle qui correspond l'emportant :
allow 203.0.113.10;
deny all;
L'authentification basique du proxy est l'autre voie : basic_auth avec Caddy, dont le mot de passe se hache par caddy hash-password, ou auth_basic et un fichier créé par htpasswd avec Nginx. Elle convient aux clients qui envoient l'identifiant à chaque appel, comme curl -u ; pour une chaîne de documentation, vérifiez que son outil sait le transmettre. Pour une instance qui reste publique, Nginx peut aussi limiter le nombre de requêtes par adresse IP avec son module limit_req, réglé sur le nombre de diagrammes de vos pages.
Kroki peut accueillir des compagnons tiers qui s'enregistrent par l'API /services. Cette découverte est désactivée par défaut, et reste toujours éteinte en mode SECURE. Si vous l'activez avec KROKI_ENABLE_COMPANION_DISCOVERY=true, la documentation demande de réserver /services à un réseau de confiance, et recommande vivement le jeton KROKI_COMPANION_REGISTRATION_TOKEN : sans lui, Kroki prévient au démarrage que tout client de la passerelle peut enregistrer un compagnon.
Asciidoctor Kroki et le plugin MkDocs visent https://kroki.io par défaut. Il suffit de leur donner l'adresse de votre serveur, préfixe https:// compris.
L'extension Asciidoctor Kroki lit l'attribut kroki-server-url, dans l'en-tête du document, en ligne de commande ou dans le playbook Antora. Ajoutez kroki-fetch-diagram pour télécharger les images à la construction plutôt que de laisser le HTML pointer vers votre serveur ; cette option demande un mode de sûreté Asciidoctor server ou plus permissif.
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:
Le plugin mkdocs-kroki-plugin lit server_url, qui reprend par défaut la variable d'environnement KROKI_SERVER_URL. Avec http_method: POST, les images sont rangées à côté de chaque page dans le site construit, et mises en cache entre deux constructions :
plugins:
- kroki:
server_url: https://diagrams.example.com
http_method: POST
La page des outils tiers de la documentation recense aussi GitLab, qui rend les diagrammes Kroki dans le Markdown, l'AsciiDoc, le reST et le Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, des extensions de Visual Studio Code et d'IntelliJ, et Kroki.jl pour Julia. Tout client HTTP fonctionne aussi, comme dans cet exemple de la documentation :
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'
Kroki est sans état : il ne garde rien entre deux requêtes, et même le registre des compagnons tiers disparaît au redémarrage. Les sources de vos diagrammes vivent dans vos dépôts de documentation, et leurs images dans vos sites construits. Sur le serveur Kroki, ce qui se sauvegarde est sa configuration :
| Élément | Ce qu’il garde | À sauvegarder |
|---|---|---|
compose.yaml | Les images, leurs étiquettes et les variables KROKI_* | Oui |
Fichier .env, s’il existe | Les variables sorties du compose.yaml, comme un jeton ou un certificat | Oui, en lieu sûr |
| Configuration du proxy | Le Caddyfile ou le bloc Nginx, et le fichier de mots de passe | Oui |
| Images Docker | Le logiciel lui-même | Non : docker compose pull les retélécharge |
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile
Adaptez la liste à votre proxy, refaites la copie à chaque changement de configuration, et envoyez-la hors du serveur. Posée sur son disque, elle entre aussi dans ses sauvegardes de nuit. Une restauration revient à reposer ces fichiers et à lancer docker compose up -d.
Avec des étiquettes fixées, changez la version des quatre images dans le compose.yaml, puis, depuis son dossier :
docker compose pull
docker compose up -d
Kroki suit la gestion sémantique des versions, et chaque version publie ses changements dans CHANGELOG.md et sur sa page de version. Lisez-les avant de mettre à jour, en particulier leur section « Security » : la 0.35.0 du 5 novembre 2026 et la 0.36.0 du 9 novembre 2026 corrigent des exécutions de code à distance par des diagrammes Bytefield et TikZ, des failles XSS sur GoAT et DBML, et des requêtes forgées côté serveur par BlockDiag et par les compagnons. Sur une instance ouverte, ces versions se déploient sans attendre.
La 0.36.0 ajoute aussi l'en-tête Content-Security-Policy par défaut et le moteur de mise en page TALA pour D2. Pour l'installation manuelle, elle documente Java 21 comme version minimale.
L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS infogéré, nos équipes prennent le serveur en main et suivent votre instance de manière proactive ; Kroki reste votre logiciel, avec sa configuration et ses compagnons.
| Sujet | Nos équipes | Vous |
|---|---|---|
| Le serveur | Mises à jour du système et de la sécurité, interventions sur le serveur comprises | Le moment qui convient à votre activité |
| La supervision | Serveur suivi 24 h/24 et 7 j/7, avec intervention sans attendre votre appel | La lecture des journaux de votre instance |
| Kroki | Suivi proactif : erreurs, lenteurs, mémoire des compagnons et espace disque repérés, correction recommandée | Son installation, ses mises à jour et ses réglages, que vous appliquez, vous ou votre assistant IA |
| Les diagrammes et l’accès | Le serveur qui les rend, surveillé et sauvegardé | Le mode de sécurité, les compagnons, les limites et les règles d’accès du proxy |
| Les sauvegardes | Chaque nuit, chiffrées et gardées hors de la machine ; restauration comprise | Les copies de votre configuration que vous gardez ailleurs, et la demande de restauration, quand vous en avez besoin |
| La migration | Votre serveur actuel migré, offert | Le moment de la bascule |
Si vous préférez que nos équipes interviennent dans l'application elle-même, cette prestation se facture à l'heure ou au forfait, avec un chiffrage communiqué avant l'intervention.
Avec un VPS infogéré Simafri, nos équipes tiennent à jour le serveur de votre instance Kroki, le surveillent jour et nuit et interviennent sans attendre votre appel ; elles suivent aussi votre instance de manière proactive et vous recommandent les corrections utiles, que vous appliquez, vous ou votre assistant IA. Les sauvegardes sont chiffrées chaque nuit et gardées hors de la machine, leur restauration est comprise, et la migration de votre serveur actuel est offerte.
Oui. Kroki est sous licence MIT : vous pouvez l'utiliser, le modifier et le redistribuer en entreprise sans licence à acheter, en gardant sa notice de copyright. Reste le coût du serveur qui le fait tourner.
Seulement pour les diagrammes qu'ils rendent. L'image yuzutech/kroki suffit pour PlantUML, GraphViz, D2, Structurizr et la plupart des formats. Mermaid, BPMN, Excalidraw et diagrams.net demandent chacun leur compagnon, relié par KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST ou KROKI_DIAGRAMSNET_HOST.
Créez un compose.yaml avec l'image yuzutech/kroki, son port 8000 publié sur 127.0.0.1, et les compagnons voulus, comme yuzutech/kroki-mermaid, reliés par les variables KROKI_*_HOST. Lancez docker compose up -d, vérifiez /health, puis placez un proxy inverse en HTTPS devant le port 8000.
Non, Kroki n'a ni comptes, ni page d'administration, ni base de données. Sa configuration tient en variables d'environnement KROKI_*, et l'accès à l'API se règle au proxy inverse, par adresse IP ou par authentification basique.
Gardez le mode SECURE, actif par défaut, qui empêche les bibliothèques de lire des fichiers ou le réseau. Laissez en place les limites de temps et de taille, mettez à jour dès qu'une version corrige une faille, et, si seule votre chaîne de publication appelle Kroki, n'acceptez que son adresse au proxy.
Avec Asciidoctor, posez l'attribut kroki-server-url sur l'adresse de votre serveur, et kroki-fetch-diagram pour télécharger les images à la construction. Avec MkDocs, réglez server_url dans la configuration du plugin kroki, et http_method: POST pour ranger les images avec le site.
Sa configuration seulement : le compose.yaml, un éventuel fichier .env et la configuration du proxy inverse. Kroki ne garde aucune donnée, et ses images Docker se retéléchargent avec docker compose pull.
Un VPS infogéré couvre le serveur : système, sécurité, supervision et sauvegardes. Nos équipes suivent aussi votre instance de manière proactive et vous recommandent les corrections utiles, que vous appliquez. Une intervention dans l'application se facture à l'heure ou au forfait.
Simafri
Parlons de votre projet
Dites-nous en deux mots ce qu'il vous faut : on revient vers vous rapidement.
Merci ! Votre demande a bien été envoyée. Nous vous répondrons rapidement.
Vous préférez l'email ? Écrivez-nous à support@simafri.com.