Kroki server

Kroki server acts as a gateway and provides a unified API on-top of diagrams libraries.

Build

$ make build

Package

To get you started quickly, you can build a Docker image:

$ sudo make package

Then you can run the server using the following command:

$ sudo docker run --publish=8000:8000 yuzutech/kroki:latest

Note	We are using the --publish option to expose the container’s port 8000 on the host’s port 8000.

The server should be running and available at: http://localhost:8000/

Configuration

KROKI_SVGBOB_BIN_PATH

Path to the svgbob binary

KROKI_ERD_BIN_PATH

Path to the erd binary

KROKI_DOT_BIN_PATH

Path to the dot binary (provided by GraphViz)

KROKI_NOMNOML_BIN_PATH

Path to the nomnoml binary

KROKI_VEGA_BIN_PATH

Path to the vega binary (it supports both Vega and Vega-Lite grammar)

KROKI_WAVEDROM_BIN_PATH

Path to the wavedrom binary

KROKI_BYTEFIELD_BIN_PATH

Path to the bytefield-svg binary

KROKI_BLOCKDIAG_HOST

The host of the blockdiag server

KROKI_BLOCKDIAG_PORT

The port of the blockdiag server

KROKI_SAFE_MODE

One of:

SECURE

(default) Paranoid sanitization of requests before passing to the diagram library.

SAFE

Assume the diagram libraries secure mode request sanitization is sufficient

UNSAFE

Run the diagram libraries without request sanitization.

Note

Some diagram libraries allow referencing external entities by URL or accessing resources from the filesystem. For example PlantUML allows the !import directive to pull fragments from the filesystem or a remote URL or the standard library. It is the responsibility of the upstream codebases to ensure that they can be safely used without risk. Because Kroki does not perform code review of these services, our default setting is to be paranoid and block imports unless known safe. We encourage anyone running their own Kroki server to review the services security settings and select the security mode appropriate for their use case.

KROKI_PLANTUML_INCLUDE_PATH

The include path to set for PlantUML.

KROKI_PLANTUML_INCLUDE_WHITELIST

The name of a file that consists of a list of Java regular expressions for valid includes.

KROKI_PLANTUML_INCLUDE_WHITELIST_0, KROKI_PLANTUML_INCLUDE_WHITELIST_1, …​ KROKI_PLANTUML_INCLUDE_WHITELIST_N

One regex to add to the include whitelist per environment variable. Search will stop at the first empty or undefined integer number.

KROKI_PLANTUML_ALLOW_INCLUDE

Either false (default) or true. Determines if PlantUML will fetch !include directives that reference external URLs

Image

The Docker image contains the following diagrams libraries as binaries:

Svgbob

/rust/bin/svgbob (statically linked)

Erd

/haskell/bin/erd (statically linked)

GraphViz

/usr/bin/dot

Nomnoml

/node/bin/nomnoml

To keep the Docker image as small as possible, the following libraries are provided as an "external" service:

• BlockDiag

• SeqDiag

• ActDiag

• NwDiag

• PacketDiag

• RackDiag

When one of the above library is requested, Kroki server will delegate the call.

PlantUML include files

As PlantUML syntax includes pre-processor directives that have the potential to access external resources, serving live content from Kroki server is only recommended when using the default settings of KROKI_SAFE_MODE=SECURE and KROKI_PLANTUML_ALLOW_INCLUDE=false.

If you are using Kroki server for offline image generation as part of your build tool chain, you may be able to change these defaults although it is not recommended.

The recommended pattern for handling includes is to either extend the docker image or bind mount a directory containing the files you wish to include and then set the KROKI_PLANTUML_INCLUDE_PATH environment variable.

For example:

$ mkdir example-lib
$ printf "@startuml\nBob->Alice\n@enduml\n" > example-lib/bob.puml
$ sudo docker run --publish=8000:8000 -v $(pwd)/example-lib:/example-lib -e KROKI_SAFE_MODE=SAFE -e KROKI_PLANTUML_INCLUDE_PATH=/example-lib yuzutech/kroki:latest
$ curl http://localhost:8000/plantuml/svg/$(printf '@startuml\n!include bob.puml\nAlice -> Bob\n@enduml' | python -c "import sys; import base64; import zlib; print(base64.urlsafe_b64encode(zlib.compress(sys.stdin.read(), 9)))")

Manual install

If you don’t want to use the Docker image, you will need to install all the dependencies on your system:

• Java 8

• GraphViz: https://graphviz.gitlab.io/download/

• Erd: https://github.com/BurntSushi/erd

• Svgbob: https://github.com/ivanceras/svgbob