DOCSEARCHbyAlgolia
Submit Docs

Kroki Documentation

website·Indexed 36 days ago

https://docs.kroki.io/kroki/

Kroki provides a unified HTTP API to convert plain text diagrams into images. It supports a wide variety of diagramming engines, including BlockDiag, D2, Ditaa, GoAT, GraphViz, Mermaid, PlantUML, Structurizr, Svgbob, and Symbolator. The documentation covers installation via Docker, Podman, Kubernetes, or manual setup, as well as usage of the Kroki CLI, HTTP client integration, and diagram configuration options.

Tokens
10.5K
Snippets
53
Records
79
Agent score
69%

What's inside Kroki

  1. Overview of Kroki diagram conversion

    Kroki provides a unified HTTP API that converts plain text diagram definitions into images. It supports a wide range of diagramming languages and tools, including:

    • BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag)
    • BPMN
    • Bytefield
    • C4 (via PlantUML)
    • Diagrams.net (experimental)
    • Ditaa
    • Erd
    • Excalidraw
    • GoAT
    • GraphViz
    • Mermaid
    • Nomnoml
    • PlantUML
    • Structurizr
    • SvgBob
    • Symbolator
    • UMLet
    • Vega and Vega-Lite
    • WaveDrom
    • WireViz

    The API is designed for simplicity: it accepts a text diagram as input and returns an image. For performance and security reasons, the public instance does not perform remote calls.

  2. Overview of Kroki diagramming service

    Kroki provides a unified API to render diagrams from a wide variety of libraries (written in languages such as Haskell, Python, JavaScript, Go, PHP, and Java) without requiring the user to install the underlying dependencies or runtimes for each library locally. It is an open-source project available on GitHub and is offered as a free service.

  3. Understand Kroki's modular architecture

    Kroki uses a modular architecture consisting of a central Gateway Server and several optional companion web servers. The Gateway Server (built with Vert.x) acts as the entry point and routes requests to the appropriate rendering service. Companion servers are typically JavaScript-based (powered by micro) and provide specific diagramming libraries like Mermaid, bpmn-js, Excalidraw, and diagrams.net.

  4. Deploy Kroki on Kubernetes using multi-pod definition files

    Install Kroki in the default namespace using a multi-pod architecture. This involves downloading a bundle of YAML definition files for Deployments, Services, and Ingress, and applying them to the cluster.
    # 1. Download and extract definition files
wget http://docs.kroki.io/kroki/setup/_attachments/kroki-k8s-multipod.zip -O kroki-k8s-multipod.zip
unzip kroki-k8s-multipod.zip -d kroki-k8s

# 2. Create objects as a batch
kubectl apply -f /path/to/kroki-k8s

  6. Deploy Kroki using a single Kubernetes Pod

    For a simpler but less flexible configuration, you can run all Kroki containers within a single pod. This requires a different set of definition files.
    # Download and extract single-pod bundle
wget http://docs.kroki.io/kroki/setup/_attachments/kroki-k8s-singlepod.zip -O kroki-k8s-singlepod.zip
unzip kroki-k8s-singlepod.zip -d kroki-k8s

# Apply the files
kubectl apply -f /path/to/kroki-k8s

  7. Convert diagrams using Kroki POST requests

    Kroki supports three ways to send diagrams via POST: as a JSON body, as plain text with headers, or as a hybrid of both.
    # Option 1: JSON body to the root endpoint
POST /
Content-Type: application/json

{
  "diagram_source": "digraph G {Hello->World}",
  "diagram_type": "graphviz",
  "output_format": "svg"
}

# Option 2: Plain text with Accept header
POST /graphviz
Accept: image/svg+xml
Content-Type: text/plain

digraph G {
  Hello->World
}

# Option 3: Plain text with format in URL
POST /graphviz/svg
Content-Type: text/plain

digraph G {
  Hello->World
}

  8. Generate and apply self-signed SSL certificates for Kroki

    You can use OpenSSL to generate a self-signed certificate and key, then pass them to the Kroki container via an environment file.
    # 1. Generate certificate and key
openssl req -nodes -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

# 2. Format for .env file (removing newlines)
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

# 3. Run container
docker run -p8000:8000 -e KROKI_SSL=true --env-file=.env yuzutech/kroki

  9. Convert diagrams using Kroki CLI

    The convert command transforms diagram files into images. By default, Kroki infers the diagram type from the input file extension and defaults the output format to SVG. You can explicitly define the type, format, and output file using options. Use - as the diagram argument to read from stdin, and - as the --out-file value to output to stdout.
    # Implicit conversion (PlantUML to SVG)
kroki convert diagram.puml

# Explicit conversion with specific format and output file
kroki convert diagram.puml --type plantuml --format svg --out-file diagram.svg

# Convert Erd diagram to PNG
kroki convert simple.er --out-file out.png

# Read from stdin and output to stdout
cat hello.dot | kroki convert - -t dot

# Read from stdin and output to file
cat hello.dot | kroki convert - -t dot -o out.png

# Read from file and output to stdout
kroki convert simple.er --out-file -

  10. Install Kroki CLI

    Kroki CLI is available for Linux, macOS, Windows, and OpenBSD. Download the archive from the official releases, extract the kroki binary to a directory, and verify the installation by running the version command. It is recommended to add the binary to your system PATH to use the kroki command globally.
    /path/to/kroki version

  11. Choose between Docker and Podman for Kroki deployment

    When deploying Kroki, the choice between Docker and Podman depends on your operating system and security requirements:

    Use Docker if:

    • You are running Windows and want a simple setup for a home machine or server.
    • Docker is already installed on your Linux system.

    Use Podman if:

    • You are running on Linux and prioritize security-by-design (e.g., running as a non-root user).
    • You are performing an organizational deployment.
    • You are testing Kroki as a precursor to deploying it in a Kubernetes environment.