Kroki provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), C4 (with PlantUML), Ditaa, Erd, GraphViz, Nomnoml, Mermaid, PlantUML, SvgBob and UMLet…​ 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.

blockdiag

A companion web server written in Python (powered by Flask and Gunicorn) that provides BlockDiag, SeqDiag, ActDiag and NwDiag diagrams libraries.

mermaid

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

Build

Gateway Server

The first step is to install the local dependencies in your local repository using make:

$ make installLocalDependencies

Then you can build the project using Maven:

$ make buildServer

Docker Images

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

$ sudo make buildDockerImages

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 BlockDiag, ActDiag, NwDiag, SeqDiag or Mermaid, then you will also need to start companion containers.

You can use docker-compose to run multiple containers:

docker-compose.yml

version: "3"
services:
  core:
    image: yuzutech/kroki
    environment:
      - KROKI_BLOCKDIAG_HOST=blockdiag
      - KROKI_MERMAID_HOST=mermaid
    ports:
      - "8000:8000"
  blockdiag:
    image: yuzutech/kroki-blockdiag
    ports:
      - "8001:8001"
  mermaid:
    image: yuzutech/kroki-mermaid
    ports:
      - "8002:8002"

$ docker-compose up -d