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://badges.gitter.im/gitterHQ/gitter.svg[Gitter chat, link=https://gitter.im/kroki-project/community] 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, GraphViz, Mermaid, Nomnoml, 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
Click to show internal directories.
Click to hide internal directories.