kroki

:uri-kroki: https://kroki.io/ :uri-kroki-docs: https://docs.kroki.io/ :uri-maven: https://maven.apache.org/ :uri-hostinger-deploy: https://www.hostg.xyz/aff_c?offer_id=815&aff_id=244069&url_id=6821

++++ ++++

ifdef::env-github[] image:https://github.com/yuzutech/kroki/actions/workflows/main.yaml/badge.svg[GitHub Actions build status, link=https://github.com/yuzutech/kroki/actions/workflows/main.yaml] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Zulip chat, link=https://kroki.zulipchat.com/] endif::[]

{uri-kroki}[Kroki] provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Diagrams.net (experimental), Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom and WireViz… and more to come!

== Hosting Providers

If you don’t want to manage the infrastructure yourself, the following third-party providers offer hosted Kroki instances:

https://www.hostinger.com/[Hostinger]:: A secure, speedy, reliable VPS hosting with built-in Docker manager. + image::https://assets.hostinger.com/vps/deploy.svg[Deploy on Hostinger,width=200,link=https://www.hostg.xyz/aff_c?offer_id=815&aff_id=244069&url_id=6821]

https://kroki.wovalab.com/[Wovalab]:: A community-run hosted Kroki instance. + image::https://kroki.wovalab.com/try-on-wovalab.svg[Try on Wovalab,link=https://kroki.wovalab.com/]

https://easypanel.io[Easypanel]:: A self-hosted Docker deployment platform, and it maintains a one-click deployment template for Kroki with the Mermaid, BPMN, and Excalidraw companion containers wired up automatically. + image::https://easypanel.io/img/deploy-on-easypanel-40.svg[Deploy on Easypanel,link=https://easypanel.io/templates/kroki]

https://zop.dev/zopday[ZopDay]:: A deployment platform that runs the Kroki image on its managed ZopCloud or in your own AWS or GCP account; the companion containers deploy the same way and connect through the KROKI_*_HOST variables. + image::https://zop.dev/deploytozopday-inkhard.svg[Deploy to ZopDay,link=https://zop.dev/zopday/app/deploy?image=yuzutech/kroki:latest&port=8000&name=kroki]

https://pethost.dev/templates/kroki/[Pethost]:: A hosting platform for personal projects, with a one-click template that runs Kroki and its Mermaid companion on a server of your own plan. + image::https://pethost.dev/button.svg[Deploy on Pethost,link=https://pethost.dev/templates/kroki/]

NOTE: These are third-party/community offerings, not officially operated by the Kroki team.

== Quickstart

This section offers a basic tutorial for evaluating Kroki. More comprehensive installation instructions are in the {uri-kroki-docs}[Kroki documentation].

== Usage

Kroki uses a simple algorithm (deflate + base64) to encode your diagram in the URL:

GET /plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

You can also call Kroki with POST:

POST /

[source,json]

{ “diagram_source”: “Bob -> Alice : hello”, “diagram_type”: “plantuml”, “output_format”: “svg” }

In this case, you don’t need to encode your diagram.

It’s also possible to send your diagram as plain text using the Content-Type header. The output format will be specified using the Accept header and the diagram source will be sent as the request body:

POST /plantuml

[source]

Accept: image/svg+xml Content-Type: text/plain

Bob -> Alice : hello

You can also define the output format in the URL if you don’t want to add an Accept header:

POST /plantuml/svg

[source]

Content-Type: text/plain

Bob -> Alice : hello

The same concept applies when sending the diagram as JSON:

POST /plantuml/svg [source,json]

{ “diagram_source”: “Bob -> Alice : hello” }

== Project layout

Kroki has a modular architecture:

server:: A Java web server (powered by Vert.x) that acts as a gateway. Kroki server is built using {uri-maven}[Maven].

umlet:: A tiny Java API on top of UMlet (mini) to generate diagrams.

nomnoml:: A Node.js CLI on top of the Nomnoml diagram library.

vega:: A Node.js CLI on top of the vega diagram library. Also supports Vega-Lite concise grammar.

mermaid:: A companion web server written in JavaScript (powered by micro) that provides Mermaid diagram library.

bpmn:: A companion web server written in JavaScript (powered by micro) that provides bpmn-js diagram library.

bytefield:: A Node.js CLI on top of the bytefield-svg diagram library.

wavedrom:: A Node.js CLI on top of the wavedrom diagram library.

excalidraw:: A companion web server written in JavaScript (powered by micro) that provides Excalidraw.

diagrams.net:: A companion web server written in JavaScript (powered by micro) that provides diagrams.net.

== Build

The versions of the build tools (Java, Node.js, Deno and task) are declared in mise.toml. Install https://mise.jdx.dev/getting-started.html[mise], then install the tools at the versions used by the CI:

$ mise install

=== Gateway Server

The first step is to build the project using Maven:

$ task mavenBuild

=== Docker Images

To build all the Docker images, use the following command:

$ task dockerBuildImages

NOTE: If your user cannot access the Docker daemon, use sudo "$(mise which task)" dockerBuildImages: sudo does not inherit the tools installed by mise.

== Run

Once the Docker images are built, you can run Kroki using docker:

$ docker run -d -p 8000:8000 yuzutech/kroki

=== Companion Containers

If you want to use one of the following diagram libraries then you will also need to start the corresponding companion container:

yuzutech/kroki-mermaid:: Mermaid

yuzutech/kroki-bpmn:: BPMN

yuzutech/kroki-excalidraw:: Excalidraw

yuzutech/kroki-diagramsnet (experimental):: diagrams.net

You can use docker-compose to run multiple containers:

.docker-compose.yml [source,yml]

services: core: image: yuzutech/kroki restart: unless-stopped environment: - KROKI_MERMAID_HOST=mermaid - KROKI_BPMN_HOST=bpmn - KROKI_EXCALIDRAW_HOST=excalidraw # experimental! - KROKI_DIAGRAMSNET_HOST=diagramsnet ports: - “8000:8000” mermaid: image: yuzutech/kroki-mermaid restart: unless-stopped expose: - “8002” bpmn: image: yuzutech/kroki-bpmn restart: unless-stopped expose: - “8003” excalidraw: image: yuzutech/kroki-excalidraw restart: unless-stopped expose: - “8004”

experimental!

diagramsnet: image: yuzutech/kroki-diagramsnet restart: unless-stopped expose: - “8005”

$ docker-compose up -d

== Maintenance

To update a third-party dependency or prepare a release, see the link:MAINTAINING.adoc[maintainer guide].