Skip to content

yuzutech/kroki

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Feb 15, 2025
d12ac6e · Feb 15, 2025
Feb 15, 2025
Jan 27, 2025
Feb 15, 2025
Feb 15, 2025
Feb 15, 2025
Feb 15, 2025
Feb 15, 2025
Feb 6, 2025
Feb 15, 2025
Feb 8, 2023
Feb 15, 2025
Feb 15, 2025
Feb 15, 2025
Aug 20, 2023
Feb 15, 2025
Feb 15, 2025
Nov 7, 2022
Feb 15, 2025
Jan 13, 2023
May 22, 2021
May 4, 2024
Mar 9, 2024
Feb 15, 2025
Mar 10, 2023
Feb 15, 2025
Aug 21, 2023
Aug 18, 2024
Jan 27, 2025
Jan 27, 2025
Oct 21, 2024
Feb 15, 2025
Nov 10, 2024
Nov 1, 2022

Repository files navigation

Kroki

GitHub Actions build status Zulip chat

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, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom and WireViz…​ and more to come!

Quickstart

This section offers a basic tutorial for evaluating Kroki. More comprehensive installation instructions are in the 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 /
{
  "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
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
Content-Type: text/plain

Bob -> Alice : hello

The same concept applies when sending the diagram as JSON:

POST /plantuml/svg
{
  "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 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

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:

$ sudo task dockerBuildImages
Note
sudo might not be needed depending on your distribution and docker configuration.

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
services:
  core:
    image: yuzutech/kroki
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "8000:8000"
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"
  # experimental!
  diagramsnet:
    image: yuzutech/kroki-diagramsnet
    expose:
      - "8005"
$ docker-compose up -d