Using Docker or Podman

This page covers how to install and run Kroki locally using the prebuilt Kroki container images from Docker Hub.

To get started fast and convert plain text diagrams to images with Kroki, you need only to install the gateway server.

We recommend installing and running Kroki locally using containers with either Docker or Podman, especially if you don’t want to manually install diagrams libraries.

On this page, you’ll learn:

  • How to get started with one container which is the minimum needed to run Kroki

  • How to run Kroki with Docker or Podman using prebuilt Kroki container images from Docker Hub

  • How to run multiple Kroki containers for serving more diagram types.

Prerequisites

Container software of choice

You will need in your environment Docker or Podman software to run the Kroki containers.

Read more about choosing Docker or Podman at About Docker and Podman for Kroki.

Kroki containers

You will need access to the Kroki container images that are either:

  • On Docker Hub via an internet connection

    This guide uses these images.

  • The above Docker Hub images stored locally

  • Your own built Kroki container images

Install the Kroki gateway server

Installing and running the Kroki gateway server by itself gets you started quickly to begin creating diagrams provided by the yuzutech/kroki image.

Assumptions:

To start the Kroki gateway server, run the command:

Using docker
docker run yuzutech/kroki
Using podman
podman run yuzutech/kroki

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 or Podman, you need to use the --publish or -p flag.

Published port

To map a container port to a port on your Docker host, you need to use the --publish or -p flag.

Using docker
docker run -p8000:8000 yuzutech/kroki
Using podman
podman run -p8000:8000 yuzutech/kroki

After the above command, the server will be available on your host at: localhost:8000

You can also map a different TCP port on the Docker host. For instance, if you want to map your host’s TCP port 1234 to port 8000 in the Kroki container, use: -p1234:8000.

In this case, the server will be available on your host at: http://localhost:1234

You can read more about Docker container networking and Podman networking in their documentation.

Detached mode

The previous methods above ran the containers in the foreground, requiring you to press control-c to stop them. Starting containers in detached mode runs them in the background, requiring you to use the Docker/Podman stop or kill command to stop them.

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

Using docker
docker run -p8000:8000 -d yuzutech/kroki
Using podman
podman run -p8000:8000 -d yuzutech/kroki

After the above command, the server will be available on your host at: localhost:8000

Run multiple Kroki containers together

Running multiple containers allows you to use all the diagram features of Kroki in your environment provided by the images. The gateway server container provided by the image yuzutech/kroki image is the minimum requirement.

Example of running them all together

Here’s an example where we start all the Kroki containers together as a group (or pod) in detached mode.

The same Kroki docker-compose.yml configuration file below is used by all examples of running the different Kroki containers together.

docker-compose.yml
services:
  kroki:
    image: yuzutech/kroki
    depends_on:
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "8000:8000"
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"

Use Docker or Podman with Docker Compose

Assumptions:

Run:

docker-compose up -d

Use Podman with podman-compose

Assumptions:

Run:

podman-compose up -d

Testing after starting

After starting the containers the servers will be available.

Test that you see the Kroki services page in your browser on your host at URL: localhost:8000