Install Kroki

To convert plain text diagrams to images with Kroki, you first need to install the gateway server.

We recommend installing Kroki using Docker, especially if you don’t want to manually install diagrams libraries.

However, you can also install each diagrams libraries that you want to use and run the gateway server as a standalone executable jar. Consult the manual install page to find out how.

Assumptions:

Docker is installed on your machine.
Docker Compose is installed on your machine (optional).

On this page, you’ll learn:

How to run Kroki
How to configure Kroki

Using Docker

docker run yuzutech/kroki

The above command will effectively start a server on port 8000.
By default, when you start a container, it does not publish any of its ports to the outside world. To make a port available to services outside of Docker, you need to use the --publish or -p flag. For instance, if you want to map TCP port 8000 in the container to port 8080 on your host, use:

docker run -p8080:8000 yuzutech/kroki

With the above command, the server will be available on your host at: localhost:8080
You can read more about container networking in the Docker documentation.

Finally, to start a container in detached mode, you use -d option:

docker run -p8080:8000 -d yuzutech/kroki

Using docker-compose

You can use docker-compose to run multiple containers. Here’s an example where we start all the containers:

docker-compose.yml

version: "3"
services:
  kroki:
    image: yuzutech/kroki
    depends_on:
      - blockdiag
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_BLOCKDIAG_HOST=blockdiag
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "8000:8000"
  blockdiag:
    image: yuzutech/kroki-blockdiag
    expose:
      - "8001"
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"

docker-compose up -d

Images

yuzutech/kroki image contains the following diagrams libraries out-of-the-box:

In other words, the following endpoints will be available:

/bytefield
/c4plantuml
/ditaa
/erd
/graphviz
/dot
/nomnoml
/plantuml
/svgbob
/umlet
/vega
/vegalite
/wavedrom

If you want to use BlockDiag, ActDiag, NwDiag, SeqDiag, Mermaid or BPMN, then you will also need to start companion containers:

yuzutech/kroki-blockdiag: Provides block, sequence, activity and network diagrams for Kroki using respectively BlockDiag, SeqDiag, ActDiag, NwDiag PacketDiag, and RackDiag libraries.
yuzutech/kroki-mermaid: Provides flowchart, sequence and Gantt diagrams for Kroki using Mermaid.
yuzutech/kroki-bpmn: Provides BPMN diagrams for Kroki using bpmn-js.
yuzutech/kroki-excalidraw: Provides BPMN diagrams for Kroki using Excalidraw.

Using Kubernetes

This section will explain how to install Kroki on Kubernetes using the default namespace.

To allow external access to your Kroki internal service, you will to publish the service using ClusterIP, NodePort, LoadBalancer or ExternalName.

In this example, we will use Ingress to expose the service on port 8000.

To learn more about how to publish a service, please consult the Kubernetes documentation

You can download a bundle (zip file) that contains all the required Deployment, Service and Ingress definition files to deploy Kroki on Kubernetes.

Once you’ve downloaded the .zip file, extract the content of the zip file into a folder named kroki-k8s.

If you have wget and unzip installed on your machine, open a terminal and type:

wget http://docs.kroki.io/kroki/setup/_attachments/kroki-k8s.zip -O kroki-k8s.zip
unzip kroki-k8s.zip -d kroki-k8s

The above commands will download the zip file and extract it into a folder named kroki-k8s.

Use the command kubectl apply to create all the required Kubernetes objects:

kubectl apply -f /path/to/kroki-k8s

Do not forget to replace /path/to/kroki-k8s with the actual path to the folder that contains the definition files (.yaml)

Alternatively, you install them individually from GitHub, open a terminal and type:

Add BlockDiag service

kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/blockdiag-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/blockdiag-service.yaml

Add Mermaid service

kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/mermaid-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/mermaid-service.yaml

Add BPMN service

kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/bpmn-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/bpmn-service.yaml

Add Excalidraw service

kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/excalidraw-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/excalidraw-service.yaml

Add Kroki service

kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/kroki-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/kroki-service.yaml

Add Ingress

kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s/kroki-ingress.yaml

Verify that Kroki service is running using kubectl get pod:

kubectl get pod

If the installation was successful, the command should report a list of running pods:

NAME                          READY   STATUS    RESTARTS   AGE
blockdiag-7bd6c989b7-zhvj8    1/1     Running   0          24s
bpmn-6cfccf9bc4-6w4px         1/1     Running   0          24s
excalidraw-5b84995fcb-dh57t   1/1     Running   0          24s
kroki-6b49bcb7c4-x2ksc        1/1     Running   0          23s
mermaid-7bff5c9959-hkrxx      1/1     Running   0          22s

To make sure that Kroki is working, open a terminal and type:

kubectl port-forward service/kroki 8000:8000

The above command will forward local port 8000 to port 8000 on the service/kroki Pod. In other words, Kroki will be accessible on localhost:8000.

Open a second terminal and type:

curl http://localhost:8000/seqdiag/svg/eNorTi1MyUxMV6jmUlBIKsovL04tUtC1UyhPTQKyyoCc6JzEpNQcBVsFJXfXEAX9zLyU1Aq9jJLcHKVYayQ9Nrq6CE3WhA0L8A8GmpaUk5-un5yfm5uaVwIxD6EWqDElsSQxKbE4FUmfp1-wa1CIAg49IFfANOFxXS0A68hQUg==

To uninstall Kroki, you can use the command kubectl delete:

kubectl delete -f /path/to/kroki-k8s