Héberger Kroki sur un VPS géré : vos diagrammes rendus chez vous

Héberger Kroki sur un VPS gé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.

Simon Vasconcelos Lee Par Publié le 20 novembre 2026Lecture : 15 minutes

Tous les guides

L'essentiel

  1. La licence MIT permet d'utiliser, de modifier et de redistribuer Kroki librement, en entreprise comme ailleurs, en gardant sa notice de copyright.
  2. Kroki transforme un diagramme écrit en texte en image, par une seule API HTTP : PlantUML, GraphViz, D2, Structurizr et bien d'autres sont dans l'image yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw et diagrams.net demandent chacun leur conteneur compagnon, relié à la passerelle par les variables KROKI_*_HOST : Docker Compose les démarre ensemble.
  4. Kroki n'a ni compte ni base de données. Il démarre en mode SECURE, qui l'empêche de lire des fichiers ou le réseau ; l'accès à une instance publique se règle au mandataire inverse.
  5. Sauvegardez la configuration, compose.yaml et celle du mandataire, puis mettez à jour avec docker compose pull en lisant chaque note de version.

Ce que fait Kroki

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.

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.

Ce que permet la licence MIT

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.

La passerelle et ses conteneurs compagnons

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.

ImageCe qu'elle rendObligatoire
yuzutech/krokiLa 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 WireVizOui
yuzutech/kroki-mermaidMermaid : diagrammes de flux, de séquence et de GanttNon
yuzutech/kroki-bpmnBPMN, avec bpmn-jsNon
yuzutech/kroki-excalidrawExcalidraw, le style dessiné à la mainNon
yuzutech/kroki-diagramsnetdiagrams.net, encore expérimentalNon

Dimensionner le serveur

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.

Sur un VPS géré, décrivez-nous vos diagrammes, les compagnons qu'ils demandent et le trafic attendu, et nous vous recommandons la taille qui convient.

L'installation avec Docker Compose

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 :

compose.yaml
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"
Terminal
docker compose up -d

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 :

compose.yaml, service à ajouter
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Vérifier que tout répond

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 :

Terminal, sur le serveur
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'

Sans Docker : le jar autonome

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 :

Terminal
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar

La configuration : des variables, ni compte ni base

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 :

VariableDéfautSon rôle
KROKI_SAFE_MODEsecureLe niveau de sécurité, détaillé plus bas
KROKI_LISTENToutes les interfaces, port 8000L'adresse et le port d'écoute ; accepte aussi un socket UNIX, unix:// et un chemin
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Où la passerelle joint chaque compagnon ; les variables _PORT correspondantes donnent le port, et KROKI_DIAGRAMSNET_HOST sert à diagrams.net
KROKI_COMMAND_TIMEOUT5 secondesL'attente maximale d'un exécutable de diagramme, comme dot
KROKI_CONVERT_TIMEOUT20 secondesL'attente maximale d'une bibliothèque Java, comme PlantUML
KROKI_DELEGATE_TIMEOUT_MS30 000L'attente maximale d'un compagnon, en millisecondes
KROKI_MAX_URI_LENGTH4 096La longueur d'adresse acceptée en GET, au-delà de laquelle Kroki répond 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'L'en-tête Content-Security-Policy envoyé avec chaque réponse
KROKI_CORS_ALLOWED_HEADERSAucun en plusLes 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.

HTTPS : le mandataire inverse

La passerelle sert l'API en HTTP. Un mandataire 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.

Avec Caddy

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 :

Caddyfile
diagrams.example.com {
	encode gzip
	reverse_proxy 127.0.0.1:8000
}

Avec Nginx

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à.

Bloc Nginx
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;
    }
}
Terminal
sudo nginx -t
sudo certbot --nginx

HTTPS sans mandataire

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 mandataire.

Protéger une instance ouverte sur Internet

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 mandataire laisse passer. Commencez par savoir qui doit atteindre votre serveur.

Qui appelle votre serveur ?

Le mode de sécurité

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.

NiveauCe qu'il fait
SECURE, par défautBloque toute tentative de lire des fichiers du système ou des ressources du réseau
SAFES'en remet à l'assainissement des requêtes fait par le mode sécurisé de chaque bibliothèque
UNSAFEDésactive toutes les protections

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 limites de taille et de temps

Les délais du tableau de configuration bornent chaque conversion. Les compagnons ajoutent les leurs, pensés contre l'épuisement des ressources :

Restreindre l'accès au mandataire

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 :

Caddyfile
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 :

Bloc Nginx, dans location /
allow 203.0.113.10;
deny all;

L'authentification basique du mandataire 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.

Les compagnons tiers

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.

Brancher Asciidoctor, MkDocs et les autres outils

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.

Asciidoctor et Antora

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.

En-tête du document AsciiDoc
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

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 :

mkdocs.yml
plugins:
  - kroki:
      server_url: https://diagrams.example.com
      http_method: POST

Les autres intégrations

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 :

Terminal
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'

Les sauvegardes : la configuration, pas de données

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émentCe qu'il gardeÀ sauvegarder
compose.yamlLes images, leurs étiquettes et les variables KROKI_*Oui
Fichier .env, s'il existeLes variables sorties du compose.yaml, comme un jeton ou un certificatOui, en lieu sûr
Configuration du mandataireLe Caddyfile ou le bloc Nginx, et le fichier de mots de passeOui
Images DockerLe logiciel lui-mêmeNon : docker compose pull les retélécharge
Terminal, dans le dossier du compose.yaml
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile

Adaptez la liste à votre mandataire, 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.

Les mises à jour

Avec des étiquettes fixées, changez la version des quatre images dans le compose.yaml, puis, depuis son dossier :

Terminal
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.

Qui fait quoi sur un VPS géré

L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS gé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.

SujetNos équipesVous
Le serveurMises à jour du système et de la sécurité, interventions sur le serveur comprisesLe moment qui convient à votre activité
La supervisionServeur suivi 24 h/24 et 7 j/7, avec intervention sans attendre votre appelLa lecture des journaux de votre instance
KrokiSuivi proactif : erreurs, lenteurs, mémoire des compagnons et espace disque repérés, correction recommandéeSon installation, ses mises à jour et ses réglages, que vous appliquez, vous ou votre assistant IA
Les diagrammes et l'accèsLe serveur qui les rend, surveillé et sauvegardéLe mode de sécurité, les compagnons, les limites et les règles d'accès du mandataire
Les sauvegardesChaque nuit, chiffrées et gardées hors de la machine ; restauration compriseLes copies de votre configuration que vous gardez ailleurs, et la demande de restauration, quand vous en avez besoin
La migrationVotre serveur actuel migré, offertLe 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.

Kroki, sur un serveur tenu pour vous

Avec un VPS gé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.

Découvrir les VPS gérés

Questions fréquentes

Kroki est-il gratuit pour une entreprise ?

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.

Faut-il installer les conteneurs compagnons de Kroki ?

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.

Comment installer Kroki avec Docker Compose ?

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 mandataire inverse en HTTPS devant le port 8000.

Kroki a-t-il un compte administrateur ?

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 mandataire inverse, par adresse IP ou par authentification basique.

Comment protéger une instance Kroki publique ?

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 mandataire.

Comment utiliser mon serveur Kroki avec Asciidoctor ou MkDocs ?

Avec Asciidoctor, définissez 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.

Que faut-il sauvegarder sur un serveur Kroki ?

Sa configuration seulement : le compose.yaml, un éventuel fichier .env et la configuration du mandataire inverse. Kroki ne garde aucune donnée, et ses images Docker se retéléchargent avec docker compose pull.

Un VPS géré couvre-t-il Kroki ?

Un VPS gé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.

Sources et documentation officielle

Contactez-nous