When you self-host Kroki on a managed VPS, you render your PlantUML, Mermaid, GraphViz, D2, BPMN or Excalidraw diagrams on a machine of your own, which our teams keep up to date and monitor day and night. Kroki is free software under the MIT license. This guide follows its official documentation: the gateway and its companion containers, installing with Docker Compose, configuration, HTTPS, protecting a public instance, connecting Asciidoctor and MkDocs, backups and updates.
By Simon Vasconcelos Lee
Published on 20 November 202614 minute read
yuzutech/kroki image.KROKI_*_HOST variables: Docker Compose starts them together.SECURE mode, which stops it from reading files or the network; access to a public instance is controlled at the reverse proxy.compose.yaml and the proxy’s, then update with docker compose pull, reading each release note first.Kroki provides a unified HTTP API that takes a diagram described as text and returns an image. Your documentation, wiki or forge sends the diagram source; Kroki answers with an SVG and, depending on the diagram type, a PNG, a PDF or a JPEG. Its README lists BlockDiag, BPMN, Bytefield, C4 with PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom and WireViz.
/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000. A web page then displays it like any other image./graphviz/svg, or in the JSON body.Kroki-Diagram-Options-* headers.The documentation of the Asciidoctor Kroki extension gives three reasons to run your own server rather than the public kroki.io instance: a corporate firewall that blocks it, latency when you are far from that European instance, and privacy, when diagram sources must stay inside your infrastructure.
Kroki is published under the MIT license. It grants, free of charge, the right to use, copy, modify, merge, publish, distribute, sublicense and sell copies of the software. You can therefore run it for your business, your team or your clients, with no license to buy.
The only condition is to keep the copyright notice and the license text in all copies or substantial portions of the software. The text provides the software “as is”, without warranty. The diagram libraries that Kroki bundles each keep their own license.
Kroki has a modular architecture. A gateway written in Java, on Vert.x, receives every request and routes it to the right library. Only the yuzutech/kroki image is mandatory: the documentation notes that, depending on your diagrams, it may be enough.
| Image | What it renders | Mandatory |
|---|---|---|
yuzutech/kroki | The gateway, plus ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML and C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom and WireViz | Yes |
yuzutech/kroki-mermaid | Mermaid: flowchart, sequence and Gantt diagrams | No |
yuzutech/kroki-bpmn | BPMN, with bpmn-js | No |
yuzutech/kroki-excalidraw | Excalidraw, the hand-drawn style | No |
yuzutech/kroki-diagramsnet | diagrams.net, still experimental | No |
The documentation gives no figure for memory or CPU. It does say what weighs most: the Mermaid, BPMN, Excalidraw and diagrams.net companions render each diagram in a headless Chromium browser. So that a burst of conversions does not exceed the container’s memory, each one caps its simultaneous renders: 6 by default for Mermaid, BPMN and diagrams.net, 4 for Excalidraw. Further requests wait their turn in a queue.
yuzutech/kroki 0.36.0 image weighs about 1 GB compressed. Kroki writes no data: it keeps nothing between two requests.amd64 and arm64.depends_on and KROKI_*_HOST lines.On a managed VPS, tell us about your diagrams, the companions they need and the traffic you expect, and we will recommend the right size.
The documentation recommends containers, Docker or Podman, so that you do not have to install each library by hand. On a server with Docker installed, create a folder and put this compose.yaml in it, taken from the 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"
# If you mount /tmp yourself, keep the exec option
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: this is the first change from the documentation’s example, which publishes 8000:8000. Kroki listens on all interfaces by default, and Docker publishes a port on every address of the server when given none. Here, the API is only reachable through the reverse proxy.expose: it stays on the internal Compose network, where the gateway reaches them by service name. The KROKI_MERMAID_HOST, KROKI_BPMN_HOST and KROKI_EXCALIDRAW_HOST variables give that name; their default ports, 8002, 8003 and 8004, need not be repeated.0.36.0 tag is the second change: the documentation’s example follows the latest version. The four images are published together under the same tag, which pins a consistent version and makes every update deliberate.For diagrams.net, still experimental, the README adds a fourth companion. Add this service, and the KROKI_DIAGRAMSNET_HOST=diagramsnet variable to the environment of kroki:
diagramsnet:
image: yuzutech/kroki-diagramsnet:0.36.0
restart: unless-stopped
expose:
- "8005"
From the server, the /health route returns the gateway’s status and the versions of the libraries it bundles. The next two requests render a GraphViz diagram through the gateway, then a Mermaid diagram through its companion:
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'
The documentation’s other route is the standalone server, published on the repository’s releases page as kroki-standalone-server-v0.36.0.jar. It requires Java 21 or later, and it includes no diagram libraries: each one is installed separately, and its path is set with a variable such as KROKI_DOT_BIN_PATH when the executable is not on the PATH. For the listening address, prefer KROKI_LISTEN, as the configuration documentation announces that KROKI_PORT will be removed:
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar
Kroki has no admin page, no user accounts and no database: its configuration is a set of environment variables, or Java system properties with the jar. In Docker Compose, they go in the environment block of the relevant service, then docker compose up -d recreates the container. The settings that matter most for a server:
| Variable | Default | What it does |
|---|---|---|
KROKI_SAFE_MODE | secure | The security level, detailed below |
KROKI_LISTEN | All interfaces, port 8000 | The listening address and port; also accepts a UNIX socket, unix:// followed by a path |
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST | 127.0.0.1 | Where the gateway reaches each companion; the matching _PORT variables set the port, and KROKI_DIAGRAMSNET_HOST serves diagrams.net |
KROKI_COMMAND_TIMEOUT | 5 seconds | The longest wait for a diagram executable, such as dot |
KROKI_CONVERT_TIMEOUT | 20 seconds | The longest wait for a Java library, such as PlantUML |
KROKI_DELEGATE_TIMEOUT_MS | 30,000 | The longest wait for a companion, in milliseconds |
KROKI_MAX_URI_LENGTH | 4,096 | The URL length accepted for GET, beyond which Kroki answers 414 |
KROKI_CONTENT_SECURITY_POLICY | script-src 'none'; object-src 'none' | The Content-Security-Policy header sent with every response |
KROKI_CORS_ALLOWED_HEADERS | None extra | Additional headers allowed for calls from another site |
Excalidraw diagrams produce long URLs. If you raise KROKI_MAX_URI_LENGTH, the documentation recommends staying at 8,192 characters or fewer, even though most browsers accept more in an <img> tag. For the largest diagrams, a POST request carries the source in the body rather than in the URL.
Kroki needs no secret to run. Two optional settings carry one: the KROKI_COMPANION_REGISTRATION_TOKEN token, useful if you enable third-party companion registration, covered in the section on protection, and a certificate’s private key, if you let Kroki handle HTTPS itself. Keep them out of any code repository.
The gateway serves its API over HTTP. A reverse proxy in front of it listens on ports 80 and 443, obtains the Let’s Encrypt certificate, encrypts the traffic and forwards it to Kroki on 127.0.0.1:8000. It is also where access is filtered, as the next section shows.
Caddy obtains and renews the certificate for the given name on its own, and its reverse_proxy directive passes the X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers with no extra setting:
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
This server block listens on port 80 so that Certbot can set up HTTPS. Two Nginx limits meet Kroki’s: a request body over 1 MB is refused by default with a 413, which client_max_body_size adjusts for large diagrams sent with POST; a request line longer than 8 KB gets a 414, which large_client_header_buffers adjusts if you raise KROKI_MAX_URI_LENGTH beyond that.
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
The documentation also describes encryption by Kroki itself: KROKI_SSL=true, with the certificate and private key in PEM format, as text through KROKI_SSL_CERT and KROKI_SSL_KEY, or as files through KROKI_SSL_CERT_PATH and KROKI_SSL_KEY_PATH. Certificate renewal is then done by hand, whereas Caddy or Certbot take care of it on their own in front of a proxy.
Kroki has no authentication: anyone who reaches the API can have it render diagrams. Its protection therefore rests on three things, described in the documentation and the release notes: the security mode, the size and time limits, and what the proxy lets through. Start by working out who needs to reach your server.
kroki-fetch-diagram, the MkDocs plugin with http_method: POST: the images are saved with the site, and the Kroki server no longer needs to be public.KROKI_SAFE_MODE sets three levels, each one including the restrictions of the previous one. The documentation explains that some libraries can read files or URLs, such as PlantUML’s !include directives, and that Kroki, which does not review their code, blocks such access by default. It invites everyone running a server to pick the level that suits their use.
| Level | What it does |
|---|---|
SECURE, the default | Prevents any attempt to read files from the file system or resources from the network |
SAFE | Relies on the request sanitization done by each library’s own secure mode |
UNSAFE | Disables every security feature |
SECURE, its !include and !includeurl are refused, and its security profile is SANDBOX. In SAFE, the profile becomes ALLOWLIST, and KROKI_PLANTUML_ALLOWLIST_URL or KROKI_PLANTUML_ALLOWLIST_PATH name what may be included.UNSAFE, their browser only loads local resources. To allow an internal image bank without leaving that mode, the documentation offers KROKI_ALLOWED_ORIGINS, or its per-companion form such as KROKI_MERMAID_ALLOWED_ORIGINS, on the companion container.UNSAFE: no !include for Structurizr, no external image for BlockDiag, no file reads for Lini.KROKI_STRUCTURIZR_SAFE_MODE or KROKI_MERMAID_SAFE_MODE, rather than lowering the whole server.On a public instance, keep SECURE. The Content-Security-Policy header, sent by default since 0.36.0, completes this defense: a script slipped into an SVG does not run on the Kroki origin, even when the image is opened directly.
The timeouts in the configuration table bound each conversion. The companions add their own, designed against resource exhaustion:
KROKI_MERMAID_MAX_TEXT_SIZE) or with more than 500 edges, with a 400, and aborts a render after 10 seconds, with a 408. These limits cannot be overridden through a request’s parameters.KROKI_MAX_BODY_SIZE).When only your publishing pipeline calls Kroki, the simplest option is to accept its IP address alone. With Caddy, the remote_ip matcher picks out the other addresses, and respond sends them a 403:
diagrams.example.com {
@external not remote_ip 203.0.113.10
respond @external 403
reverse_proxy 127.0.0.1:8000
}
With Nginx, the allow and deny directives of the location block do the same job, the first matching rule winning:
allow 203.0.113.10;
deny all;
The proxy’s basic authentication is the other route: basic_auth with Caddy, whose password is hashed with caddy hash-password, or auth_basic and a file created with htpasswd with Nginx. It suits clients that send the credentials with each call, such as curl -u; for a documentation pipeline, check that its tool can pass them on. For an instance that stays public, Nginx can also limit the number of requests per IP address with its limit_req module, tuned to the number of diagrams on your pages.
Kroki can host third-party companions that register through the /services API. This discovery is disabled by default, and always stays off in SECURE mode. If you enable it with KROKI_ENABLE_COMPANION_DISCOVERY=true, the documentation asks you to keep /services on a trusted network, and strongly recommends the KROKI_COMPANION_REGISTRATION_TOKEN token: without it, Kroki warns at startup that any client of the gateway can register a companion.
Asciidoctor Kroki and the MkDocs plugin target https://kroki.io by default. All they need is your server’s URL, https:// prefix included.
The Asciidoctor Kroki extension reads the kroki-server-url attribute, in the document header, on the command line or in the Antora playbook. Add kroki-fetch-diagram to download the images at build time instead of having the HTML point to your server; this option requires an Asciidoctor safe mode of server or lower.
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:
The mkdocs-kroki-plugin plugin reads server_url, which defaults to the KROKI_SERVER_URL environment variable. With http_method: POST, the images are stored next to each page in the built site, and cached between two builds:
plugins:
- kroki:
server_url: https://diagrams.example.com
http_method: POST
The documentation’s third-party tools page also lists GitLab, which renders Kroki diagrams in Markdown, AsciiDoc, reST and Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, extensions for Visual Studio Code and IntelliJ, and Kroki.jl for Julia. Any HTTP client works too, as in this example from the documentation:
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'
Kroki is stateless: it keeps nothing between two requests, and even the registry of third-party companions is gone after a restart. Your diagram sources live in your documentation repositories, and their images in your built sites. On the Kroki server, what gets backed up is its configuration:
| Item | What it holds | Back it up |
|---|---|---|
compose.yaml | The images, their tags and the KROKI_* variables | Yes |
.env file, if any | Variables kept out of compose.yaml, such as a token or a certificate | Yes, somewhere safe |
| Proxy configuration | The Caddyfile or the Nginx block, and the password file | Yes |
| Docker images | The software itself | No: docker compose pull downloads them again |
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile
Adapt the list to your proxy, make a new copy after each configuration change, and send it off the server. Stored on its disk, it is also included in its nightly backups. A restore means putting these files back and running docker compose up -d.
With pinned tags, change the version of the four images in compose.yaml, then, from its folder:
docker compose pull
docker compose up -d
Kroki follows semantic versioning, and each version publishes its changes in CHANGELOG.md and on its release page. Read them before updating, especially their “Security” section: 0.35.0 of 5 November 2026 and 0.36.0 of 9 November 2026 fix remote code execution through Bytefield and TikZ diagrams, XSS flaws in GoAT and DBML, and server-side request forgery through BlockDiag and the companions. On an open instance, deploy these versions without waiting.
Version 0.36.0 also adds the default Content-Security-Policy header and the TALA layout engine for D2. For the manual install, it documents Java 21 as the minimum version.
Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Kroki remains your software, with its configuration and its companions.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s logs |
| Kroki | Proactive monitoring: errors, slowdowns, companion memory and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Diagrams and access | The server that renders them, monitored and backed up | The security mode, the companions, the limits and the proxy’s access rules |
| Backups | Every night, encrypted and kept off the machine; restores included | The copies of your configuration you keep elsewhere, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Kroki instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.
Yes. Kroki is under the MIT license: you can use, modify and redistribute it at work with no license to buy, as long as you keep its copyright notice. What remains is the cost of the server that runs it.
Only for the diagrams they render. The yuzutech/kroki image is enough for PlantUML, GraphViz, D2, Structurizr and most formats. Mermaid, BPMN, Excalidraw and diagrams.net each need their companion, connected through KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST or KROKI_DIAGRAMSNET_HOST.
Create a compose.yaml with the yuzutech/kroki image, its port 8000 published on 127.0.0.1, and the companions you need, such as yuzutech/kroki-mermaid, connected through the KROKI_*_HOST variables. Run docker compose up -d, check /health, then put an HTTPS reverse proxy in front of port 8000.
No, Kroki has no accounts, no admin page and no database. Its configuration is a set of KROKI_* environment variables, and access to the API is controlled at the reverse proxy, by IP address or with basic authentication.
Keep SECURE mode, on by default, which stops the libraries from reading files or the network. Leave the time and size limits in place, update as soon as a version fixes a vulnerability, and, if only your publishing pipeline calls Kroki, accept only its address at the proxy.
With Asciidoctor, set the kroki-server-url attribute to your server’s URL, and kroki-fetch-diagram to download the images at build time. With MkDocs, set server_url in the kroki plugin configuration, and http_method: POST to store the images with the site.
Only its configuration: compose.yaml, any .env file and the reverse proxy configuration. Kroki keeps no data, and its Docker images download again with docker compose pull.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.