Configuration

Kroki can be configured using environment variables or Java system properties.

Server Listening

By default, Kroki will bind to all network interfaces (0.0.0.0) on port 8000. You can change on which host and port the server will listen for incoming requests using KROKI_LISTEN:

KROKI_LISTEN=127.0.0.1:1234 java -jar kroki-server.jar
java -DKROKI_LISTEN=127.0.0.1:1234 -jar kroki-server.jar

With the above configuration, the server will bind to 127.0.0.1 (i.e., loopback address) on port 1234.

If the port is unspecified, the server will listen on port 8000. If the host is unspecified, the server will use [::] (i.e., bind to all network interfaces and accept connections from both IPv6 or IPv4 hosts)

KROKI_LISTEN also accepts IPv6 enclosed within square brackets ([ and ]), for instance: KROKI_LISTEN=[2001:db8:1f70::999:de8:7648:6e8]:1234.

KROKI_PORT is deprecated and will be removed in the future.

We are deprecating this option because it conflicts with Kubernetes and Docker built-in environnement variables. For reference, Kubernetes will automatically set the environment variable {SERVICE_NAME}_PORT to tcp://1.2.3.4:8000. As you might have guessed, if you use KROKI as a service name, there’s going to be a problem! In fact, Kroki expects the value of KROKI_PORT to be an integer value.
To workaround this issue, until KROKI_PORT is removed, you can explicitly define the environment variable KROKI_PORT=8000.

If you were using a custom port (for instance, KROKI_PORT=1234), you can replace it by KROKI_LISTEN=0.0.0.0:1234 (which is strictly equivalent).
If you want to bind to IPv4 and IPv6, you can use KROKI_LISTEN=:1234 or the longer form KROKI_LISTEN=[::]:1234.

If you want to learn about this deprecation, you can read: github.com/yuzutech/kroki/issues/576

Safe Mode

Kroki provides security levels that restrict access to files on the file system and on the network. Each level includes the restrictions enabled in the prior security level:

  • UNSAFE: disables any security features.

  • SAFE: Assume the diagram libraries secure mode request sanitization is sufficient.

  • SECURE: prevents attempts to read files from the file system or from the network.

By default, Kroki is running in SECURE mode.

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.

While running in SECURE mode, Kroki will prevent PlantUML from including files using the !include or !includeurl directive.

If you want to enable this feature, you can set the safe mode using the environment variable KROKI_SAFE_MODE:

java -DKROKI_SAFE_MODE=unsafe -jar kroki-server.jar
The value is case-insensitive, so both UNSAFE and unsafe will work.

It’s also possible to restrict the PlantUML !include directive using the following environment variables when running in SAFE mode:

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.For example, PlantUML allows the !import directive to pull fragments from the filesystem or a remote URL or the standard library.

Diagram Binary Paths

Kroki depends on external binaries to generate images. By default, Kroki will locate these binaries in the PATH environment variable.

In case you’ve installed a diagram library in a way where the executable is not in the PATH, you can override its location manually using an environment variable or a Java system property:

KROKI_SVGBOB_BIN_PATH

Path to svgbob binary

KROKI_ERD_BIN_PATH

Path to erd binary

KROKI_DOT_BIN_PATH

Path to dot binary

KROKI_NOMNOML_BIN_PATH

Path to nomnoml binary

KROKI_BYTEFIELD_BIN_PATH

Path to the bytefield-svg binary

KROKI_VEGA_BIN_PATH

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

KROKI_WAVEDROM_BIN_PATH

Path to wavedrom binary

For instance, if dot is located at /path/to/dot, you can configure the path using a system property:

java -DKROKI_DOT_BIN_PATH=/path/to/dot -jar kroki-server.jar

Command Timeout

By default, Kroki will wait at most 5 seconds when calling a diagram binary to get a response. In most scenarios, 5 seconds is more than enough but, if needed, you can adjust the timeout using the KROKI_COMMAND_TIMEOUT environment variable.

The expected format is a duration with a time unit:

d

Days

h

Hours

m

Minutes

s

Seconds

ms

Milliseconds

micros

Microseconds

nanos

Nanoseconds

A few examples:

KROKI_COMMAND_TIMEOUT=10s 
KROKI_COMMAND_TIMEOUT=1m 
KROKI_COMMAND_TIMEOUT=4000ms 
1 10 seconds
2 1 minute
3 4 seconds in milliseconds

Convert Timeout

By default, Kroki will wait at most 20 seconds when calling a Java library to convert a digram. In most scenarios, 20 seconds is more than enough but, if needed, you can adjust the timeout using the KROKI_CONVERT_TIMEOUT environment variable.

The expected format is a duration with a time unit:

d

Days

h

Hours

m

Minutes

s

Seconds

ms

Milliseconds

micros

Microseconds

nanos

Nanoseconds

A few examples:

KROKI_CONVERT_TIMEOUT=10s 
KROKI_CONVERT_TIMEOUT=1m 
KROKI_CONVERT_TIMEOUT=4000ms 
1 10 seconds
2 1 minute
3 4 seconds in milliseconds

You can also configure a specific timeout for each diagram library. Currently, only PlantUML supports this configuration:

  • KROKI_PLANTUML_CONVERT_TIMEOUT

Please note that this specific configuration will override KROKI_CONVERT_TIMEOUT. In other words, diagram library timeouts (for instance, KROKI_PLANTUML_CONVERT_TIMEOUT) have higher precedence than KROKI_CONVERT_TIMEOUT.

Companion Container Host and Port

You can configure the host and port on which every companion container will be listening:

KROKI_BLOCKDIAG_HOST

Host of the BlockDiag container (default: 127.0.0.1).

KROKI_BLOCKDIAG_PORT

Port of the BlockDiag container (default: 8001).

KROKI_MERMAID_HOST

Host of the Mermaid container (default: 127.0.0.1).

KROKI_MERMAID_PORT

Port of the Mermaid container (default: 8002).

KROKI_BPMN_HOST

Host of the BPMN container (default: 127.0.0.1).

KROKI_BPMN_PORT

Port of the BPMN container (default: 8003).

KROKI_EXCALIDRAW_HOST

Host of the Excalidraw container (default: 127.0.0.1).

KROKI_EXCALIDRAW_PORT

Port of the Excalidraw container (default: 8004).

If you are using the default docker-compose.yaml file you can rely on the default values.