kroki

README

= image:https://kroki.io/assets/logo.svg[Kroki,200,link={uri-kroki}]
:uri-kroki: https://kroki.io/
:uri-kroki-docs: https://docs.kroki.io/
:uri-maven: https://maven.apache.org/

ifdef::env-github[]
image:https://travis-ci.org/yuzutech/kroki.svg?branch=master[Travis build status, link=https://travis-ci.org/yuzutech/kroki]
image:https://github.com/yuzutech/kroki/workflows/CI/badge.svg?branch=master[GitHub Actions build status, link=https://github.com/yuzutech/kroki/actions]
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), Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, UMLet, Vega, Vega-Lite and WaveDrom... and more to come!

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

blockdiag::
A companion web server written in Python (powered by _Flask_ and _Gunicorn_) that provides _BlockDiag_, _SeqDiag_, _ActDiag_, _NwDiag_, _PacketDiag_ and _RackDiag_ diagrams libraries.

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

== 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

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 _BlockDiag_, _ActDiag_, _NwDiag_, _SeqDiag_, _PacketDiag_, _RackDiag_ or _Mermaid_, then you will also need to start companion containers.

You can use `docker-compose` to run multiple containers:

.docker-compose.yml
[source,yml]
----
version: "3"
services:
  core:
    image: yuzutech/kroki
    environment:
      - KROKI_BLOCKDIAG_HOST=blockdiag
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "8000:8000"
  blockdiag:
    image: yuzutech/kroki-blockdiag
    ports:
      - "8001:8001"
  mermaid:
    image: yuzutech/kroki-mermaid
    ports:
      - "8002:8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    ports:
      - "8003:8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    ports:
      - "8004:8004"
----

 $ docker-compose up -d