Kroki

Creates diagrams from textual descriptions!

Diagram / Flow chart
yuzutech/krokikroki.io

README

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, 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 /

  1. ``` json
  2. {
  3.   "diagram_source": "Bob -> Alice : hello",
  4.   "diagram_type": "plantuml",
  5.   "output_format": "svg"
  6. }
  7. ```

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-Typeheader. The output format will be specified using the Acceptheader and the diagram source will be sent as the request body:

POST /plantuml

  1. ``` null
  2. Accept: image/svg+xml
  3. Content-Type: text/plain

  5. Bob -> Alice : hello
  6. ```

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

POST /plantuml/svg

  1. ``` null
  2. Content-Type: text/plain

  4. Bob -> Alice : hello
  5. ```

The same concept applies when sending the diagram as JSON:

POST /plantuml/svg

  1. ``` json
  2. {
  3.   "diagram_source": "Bob -> Alice : hello"
  4. }
  5. ```

Project layout


Kroki has a modular architecture:

serverA Java web server (powered by Vert.x) that acts as a gateway. Kroki server is built using Maven .

umletA tiny Java API on top of UMlet(mini) to generate diagrams.

nomnomlA Node.js CLI on top of the Nomnomldiagram library.

vegaA Node.js CLI on top of the vegadiagram library. Also supports Vega-Lite concise grammar.

blockdiagA companion web server written in Python (powered by Flaskand Gunicorn) that provides BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiagand RackDiagdiagrams libraries.

mermaidA companion web server written in JavaScript (powered by micro) that provides Mermaiddiagram library.

bpmnA companion web server written in JavaScript (powered by micro) that provides bpmn-jsdiagram library.

bytefieldA Node.js CLI on top of the bytefield-svgdiagram library.

wavedromA Node.js CLI on top of the wavedromdiagram library.

excalidrawA companion web server written in JavaScript (powered by micro) that provides Excalidraw.

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

wirevizA companion web server written in Python (powered by Flaskand Gunicorn) that provides WireViz.

Build


Gateway Server


The first step is to build the project using Maven:

$ make buildServer

Docker Images


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

$ sudo make buildDockerImages

|   |   |
| :--- | :--- |
| 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-blockdiagBlockDiag, ActDiag, NwDiag, SeqDiag, PacketDiag, RackDiag

yuzutech/kroki-mermaidMermaid

yuzutech/kroki-bpmnBPMN

yuzutech/kroki-excalidrawExcalidraw

yuzutech/kroki-diagramsnet (experimental)diagrams.net

yuzutech/kroki-wirevizWireViz

You can use docker-composeto run multiple containers:

docker-compose.yml

  1. ``` yaml
  2. version: "3"
  3. services:
  4.   core:
  5.     image: yuzutech/kroki
  6.     environment:
  7.       - KROKI_BLOCKDIAG_HOST=blockdiag
  8.       - KROKI_MERMAID_HOST=mermaid
  9.       - KROKI_BPMN_HOST=bpmn
  10.       - KROKI_EXCALIDRAW_HOST=excalidraw
  11.       - KROKI_WIREVIZ_HOST=wireviz
  12.     ports:
  13.       - "8000:8000"
  14.   blockdiag:
  15.     image: yuzutech/kroki-blockdiag
  16.     expose:
  17.       - "8001"
  18.   mermaid:
  19.     image: yuzutech/kroki-mermaid
  20.     expose:
  21.       - "8002"
  22.   bpmn:
  23.     image: yuzutech/kroki-bpmn
  24.     expose:
  25.       - "8003"
  26.   excalidraw:
  27.     image: yuzutech/kroki-excalidraw
  28.     expose:
  29.       - "8004"
  30.   # experimental!
  31.   diagramsnet:
  32.     image: yuzutech/kroki-diagramsnet
  33.     expose:
  34.       - "8005"
  35.   wireviz:
  36.     image: yuzutech/kroki-wireviz
  37.     ports:
  38.       - "8006:8006"
  39. ```

$ docker-compose up -d