Using Kroki in GitLab

What file formats do you use to manage documents in GitLab? You may use MS Word, Excel, PDF, Markdown and so on. If your reviewer are in your organization, the Markdown is useful. There are some advantages:

  • Git manages version history of files.
  • GitLab can be browsed with a web browser and markdown files are rendered in your browser.

You may have trouble if you want to insert diagrams.

What application you use to make diagrams?

GitLab can render diagrams in the markdown files. It supports SVG, PNG and any other famous image file formats. It is important that what application to use for making diagrams. Markdown is a simple text file and easily to be updated.

How about a diagram? If the specific application is needed to be updated, it may be hard to be updated.

Documents for the engineer, I recommend the Markdown. With Kroki, you can write diagrams by text.

GitLab supports Kroki

GitLab supports Kroki. Kroki presents the API for generating images from text. For example, you write the UML with plant UML syntax, Kroki generates the UML from it.

One of famous text based UML generator is PlantUML, Kroki supports it. If you write UML with PlantUML format in the markdown file, GitLab will show the rendered UML. GitLab generates the UML image by using Kroki.

Supported syntax by Kroki is not only PlantUML. There are many syntax that Kroki supports. Please see official site.

Install Kroki on your server

Kroki can be installed on your server or cloud instance with a docker.

[1] Create docker-compose.yml file.

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"
[2] Run the daemon.

% docker-compose up -d

Configure the GitLab

Configure the GitLab to access to Kroki.

[1] Select “General” in “Settings” in “Admin Area”.

[2] Click “Expand” button of “Kroki”.

[3] Turn on “Enable Kroki” check box.

[4] Enter the URL to Kroki in the docker container into the “Kroki URL” field. The port number is 8000. The port number is specified in docker-compose.yml file.

[5] Turn on “Additional diagram formats” if you have not special reason.

[6] Click the “Save changes” button.

There is a PlantUML option under Kroki option. Kroki supports PlantUML so you need not configure this option.

GitLab Kroki Option

Test

Create the sample markdown file in your git repository.

WebIDE also also render the UML in the preview.

# Sample Markdown

Write the UML in the code block.

You need specify the tool generates the image. If the tools is missing, render the block as simple code block.

## Sample Chart

### PlantUML

```plantuml
@startuml
GitLab -> Kroki: Request rendering
Kroki -> PlantUML: Request rendering
PlantUML -> Kroki: Image
Kroki -> GitLab: Image
@enduml
```

### Mermaid

```mermaid
sequenceDiagram
GitLab->>Kroki: Request rendering
Kroki->>Mermaid: Request rendering
Mermaid-->>Kroki: Image
Kroki-->>GitLab: Image
```

Sample Markdown File Rendering Preview

Sponsored Links
Get the Latest News !

ServerLatest 8 Posts