Self-host Kroki on a managed VPS: your diagrams rendered on your own server

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.

Simon Vasconcelos Lee By Published on 20 November 202614 minute read

All guides

In short

  1. The MIT license lets you use, modify and redistribute Kroki freely, at work or anywhere else, as long as you keep its copyright notice.
  2. Kroki turns a diagram written as text into an image through a single HTTP API: PlantUML, GraphViz, D2, Structurizr and many more ship in the yuzutech/kroki image.
  3. Mermaid, BPMN, Excalidraw and diagrams.net each need their own companion container, connected to the gateway through the KROKI_*_HOST variables: Docker Compose starts them together.
  4. Kroki has no accounts and no database. It starts in SECURE mode, which stops it from reading files or the network; access to a public instance is controlled at the reverse proxy.
  5. Back up the configuration, compose.yaml and the proxy’s, then update with docker compose pull, reading each release note first.

What Kroki does

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.

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.

What the MIT license allows

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.

The gateway and its companion containers

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.

ImageWhat it rendersMandatory
yuzutech/krokiThe 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 WireVizYes
yuzutech/kroki-mermaidMermaid: flowchart, sequence and Gantt diagramsNo
yuzutech/kroki-bpmnBPMN, with bpmn-jsNo
yuzutech/kroki-excalidrawExcalidraw, the hand-drawn styleNo
yuzutech/kroki-diagramsnetdiagrams.net, still experimentalNo

Sizing the server

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.

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.

Installing with Docker Compose

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:

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

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:

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

Checking that everything answers

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:

Terminal, on the server
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'

Without Docker: the standalone jar

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:

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

Configuration: variables, no accounts, no database

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:

VariableDefaultWhat it does
KROKI_SAFE_MODEsecureThe security level, detailed below
KROKI_LISTENAll interfaces, port 8000The listening address and port; also accepts a UNIX socket, unix:// followed by a path
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Where the gateway reaches each companion; the matching _PORT variables set the port, and KROKI_DIAGRAMSNET_HOST serves diagrams.net
KROKI_COMMAND_TIMEOUT5 secondsThe longest wait for a diagram executable, such as dot
KROKI_CONVERT_TIMEOUT20 secondsThe longest wait for a Java library, such as PlantUML
KROKI_DELEGATE_TIMEOUT_MS30,000The longest wait for a companion, in milliseconds
KROKI_MAX_URI_LENGTH4,096The URL length accepted for GET, beyond which Kroki answers 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'The Content-Security-Policy header sent with every response
KROKI_CORS_ALLOWED_HEADERSNone extraAdditional 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.

HTTPS: the reverse proxy

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.

With Caddy

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:

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

With Nginx

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.

Nginx server block
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 without a proxy

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.

Protecting an instance open to the Internet

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.

Who calls your server?

The security mode

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.

LevelWhat it does
SECURE, the defaultPrevents any attempt to read files from the file system or resources from the network
SAFERelies on the request sanitization done by each library’s own secure mode
UNSAFEDisables every security feature

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.

Size and time limits

The timeouts in the configuration table bound each conversion. The companions add their own, designed against resource exhaustion:

Restricting access at the proxy

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:

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

Nginx block, inside location /
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.

Third-party companions

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.

Connecting Asciidoctor, MkDocs and other tools

Asciidoctor Kroki and the MkDocs plugin target https://kroki.io by default. All they need is your server’s URL, https:// prefix included.

Asciidoctor and Antora

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.

AsciiDoc document header
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

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:

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

Other integrations

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:

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

Backups: configuration, no data

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:

ItemWhat it holdsBack it up
compose.yamlThe images, their tags and the KROKI_* variablesYes
.env file, if anyVariables kept out of compose.yaml, such as a token or a certificateYes, somewhere safe
Proxy configurationThe Caddyfile or the Nginx block, and the password fileYes
Docker imagesThe software itselfNo: docker compose pull downloads them again
Terminal, in the compose.yaml folder
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.

Updates

With pinned tags, change the version of the four images in compose.yaml, then, from its folder:

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

Who does what on a managed VPS

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.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s logs
KrokiProactive monitoring: errors, slowdowns, companion memory and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
Diagrams and accessThe server that renders them, monitored and backed upThe security mode, the companions, the limits and the proxy’s access rules
BackupsEvery night, encrypted and kept off the machine; restores includedThe copies of your configuration you keep elsewhere, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe 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.

Kroki, on a server run for you

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.

Explore Managed VPS

Frequently asked questions

Is Kroki free for a business?

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.

Do I need the Kroki companion containers?

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.

How do I install Kroki with Docker Compose?

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.

Does Kroki have an admin account?

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.

How do I protect a public Kroki instance?

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.

How do I use my Kroki server with Asciidoctor or MkDocs?

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.

What should I back up on a Kroki server?

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.

Does a managed VPS cover Kroki?

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.

Contact us