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.

In addition, KROKI_LISTEN supports UNIX domain sockets by prefixing unix:// to a path, for example: KROKI_LISTEN=unix:///var/run/kroki.sock.

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

Cross-origin resource sharing (CORS)

By default, the following headers are allowed:

  • Access-Control-Allow-Origin

  • Origin

  • Content-Type

  • Accept

If you need to pass additional headers, you can use KROKI_CORS_ALLOWED_HEADERS to allow additional headers. For instance, if you need to allow x-requested-with and x-app-version headers:

KROKI_CORS_ALLOWED_HEADERS="x-requested-with,x-app-version"

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_BYTEFIELD_BIN_PATH

Path to the bytefield-svg binary (defaults: /usr/bin/bytefield)

KROKI_D2_BIN_PATH

Path to d2 binary (defaults: /usr/bin/d2)

KROKI_DBML_BIN_PATH

Path to dbml binary (defaults: /usr/bin/dbml)

KROKI_DITAA_BIN_PATH

Path to ditaa binary (defaults: /usr/bin/ditaa)

KROKI_DOT_BIN_PATH

Path to dot binary (defaults: /usr/bin/dot)

KROKI_ERD_BIN_PATH

Path to erd binary (defaults: /usr/bin/erd)

KROKI_NOMNOML_BIN_PATH

Path to nomnoml binary (defaults: /usr/bin/nomnoml)

KROKI_PIKCHR_BIN_PATH

Path to pikchr binary (defaults: /usr/bin/pikchr)

KROKI_PLANTUML_BIN_PATH

Path to plantuml binary (defaults: /usr/bin/plantuml)

KROKI_SVGBOB_BIN_PATH

Path to svgbob binary (defaults: /usr/bin/svgbob)

KROKI_SYMBOLATOR_BIN_PATH

Path to symbolator binary (defaults: /usr/bin/symbolator)

KROKI_TIKZ2SVG_BIN_PATH

Path to tikz2svg binary (defaults: /usr/bin/tikz2svg)

KROKI_UMLET_BIN_PATH

Path to umlet binary (defaults: /usr/bin/umlet)

KROKI_VEGA_BIN_PATH

Path to vega binary which supports both Vega and Vega-Lite grammar (defaults: /usr/bin/bytefield)

KROKI_WAVEDROM_BIN_PATH

Path to wavedrom binary (defaults: /usr/bin/wavedrom)

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 (1)
KROKI_COMMAND_TIMEOUT=1m (2)
KROKI_COMMAND_TIMEOUT=4000ms (3)
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 diagram. 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 (1)
KROKI_CONVERT_TIMEOUT=1m (2)
KROKI_CONVERT_TIMEOUT=4000ms (3)
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_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.

Max URI length

Some diagrams, like Excalidraw, have verbose textual descriptions that will produce long URI. If the URI requested by the client is longer than the server is willing to interpret, the server will return a 414 (Request-URI Too Long) response status code. The default max URI length in Vert.x is 4096. You can update this default value by setting KROKI_MAX_URI_LENGTH environment variable.

Keep in mind that browsers also have a URI limit on <img> tags. Most modern browsers support a URI length greater than 64000 on <img> tags but this value is probably a bit excessive. We recommend to use a maximum length that’s not greater than 8192 and not greater than 5120 if you are supporting IE 11.

Max header size

KROKI_MAX_HEADER_SIZE

The maximum length of all headers. If the sum of the length of each header exceeds this value, 431 (Request Header Fields Too Large) response status code is sent. Defaults to 8192.

Max body size

KROKI_MAX_BODY_SIZE

The maximum size of the http body. If the size of the body exceeds this value, 413 (Content Too Large) response status code is sent. Defaults to 1mb.

These variables are only available on the diagrams.net, excalidraw and mermaid containers.

Excalidraw static assets

By default, Excalidraw loads assets from a public CDN (unpkg.com).

It’s possible to change this behavior by setting the KROKI_EXCALIDRAW_ASSET_PATH environment variable, which is empty by default.

More information about Excalidraw' static assets can be found here: docs.excalidraw.com/docs/@excalidraw/excalidraw/installation

Enabling SSL on the server

By default, SSL/TLS is not enabled on the server but you can enable it by setting KROKI_SSL environment variable to true.

When SSL is enabled, you must provide the certificate and the private key in one of two ways:

  • As strings in PEM format using the KROKI_SSL_KEY and KROKI_SSL_CERT environment variables, e.g.,:

    KROKI_SSL_KEY="-----BEGIN RSA PRIVATE KEY-----<PRIVATE_KEY>-----END RSA PRIVATE KEY-----"
  • As PEM file paths using the KROKI_SSL_KEY_PATH and KROKI_SSL_CERT_PATH environment variables.

    KROKI_SSL_KEY_PATH="/etc/ssl/certs/mydomain/privatekey.pem"

If both methods are used, the values in KROKI_SSL_KEY and KROKI_SSL_CERT are given priority.

You can generate a self-signed SSL certificate and private key as PEM format using openssl:

openssl req -nodes -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

The above command will generate two files, cert.pem containing the certificate and key.pem containing the private key.

You can then write the KROKI_SSL_CERT environment variable with the contents of the cert.pem file and the KROKI_SSL_KEY environment variable with the contents of the key.pem to an environment-file:

cat cert.pem | tr -d '\n' | sed 's/^/KROKI_SSL_CERT=/' >> .env
echo >> .env
cat key.pem | tr -d '\n' | sed 's/^/KROKI_SSL_KEY=/' >> .env

The container can then be started with the environment variables set accordingly:

Using docker
docker run -p8000:8000 -e KROKI_SSL=true --env-file=.env yuzutech/kroki
Using podman
podman run -p8000:8000 -e KROKI_SSL=true --env-file=.env yuzutech/kroki

If SSL is enabled, both KROKI_SSL_KEY (or KROKI_SSL_KEY_PATH) and KROKI_SSL_CERT (or KROKI_SSL_CERT_PATH) must be configured.