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.

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.