Hostovat Kroki na Managed VPS: vaše diagramy vykreslované na vašem serveru

Hostovat Kroki na Managed VPS znamená vykreslovat vaše diagramy PlantUML, Mermaid, GraphViz, D2, BPMN nebo Excalidraw na vlastním stroji, který naše týmy udržují aktuální a ve dne i v noci hlídají. Kroki je svobodný software pod licencí MIT. Tento průvodce sleduje jeho oficiální dokumentaci: bránu a její doprovodné kontejnery, instalaci pomocí Docker Compose, konfiguraci, HTTPS, ochranu veřejné instance, připojení Asciidoctoru a MkDocs, zálohy a aktualizace.

Simon Vasconcelos Lee Autor: Publikováno 20. listopadu 2026Doba čtení: 14 minut

Všichni průvodci

To nejdůležitější

  1. Licence MIT vám umožňuje Kroki volně používat, upravovat a dále šířit, v práci i kdekoli jinde, pokud zachováte jeho upozornění o autorských právech.
  2. Kroki převádí diagram zapsaný jako text na obrázek prostřednictvím jediného HTTP API: PlantUML, GraphViz, D2, Structurizr a mnoho dalších je součástí obrazu yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw a diagrams.net potřebují každý svůj doprovodný kontejner, připojený k bráně přes proměnné KROKI_*_HOST: Docker Compose je spouští společně.
  4. Kroki nemá účty ani databázi. Startuje v režimu SECURE, který mu brání číst soubory nebo přistupovat k síti; přístup k veřejné instanci se řídí na reverzní proxy.
  5. Zálohujte konfiguraci, compose.yaml i konfiguraci proxy, a aktualizujte příkazem docker compose pull, vždy po přečtení poznámek k vydání.

Co Kroki umí

Kroki poskytuje jednotné HTTP API, které přijme diagram popsaný textem a vrátí obrázek. Vaše dokumentace, wiki nebo platforma pro správu kódu odešle zdrojový text diagramu; Kroki odpoví obrázkem SVG a podle typu diagramu také PNG, PDF nebo JPEG. Jeho README uvádí BlockDiag, BPMN, Bytefield, C4 s PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom a WireViz.

Dokumentace rozšíření Asciidoctor Kroki uvádí tři důvody, proč provozovat vlastní server místo veřejné instance kroki.io: firemní firewall, který ji blokuje, latenci, když jste od této evropské instance daleko, a důvěrnost, když zdrojové texty diagramů musí zůstat ve vaší infrastruktuře.

Co licence MIT umožňuje

Kroki je zveřejněn pod licencí MIT. Ta bezplatně uděluje právo software používat, kopírovat, upravovat, slučovat, zveřejňovat, šířit, sublicencovat a prodávat jeho kopie. Můžete ho tedy provozovat pro svou firmu, svůj tým nebo své klienty, aniž byste kupovali licenci.

Jedinou podmínkou je zachovat upozornění o autorských právech a text licence ve všech kopiích nebo podstatných částech softwaru. Text poskytuje software „tak, jak je“, bez záruky. Knihovny diagramů, které Kroki obsahuje, si každá ponechávají vlastní licenci.

Brána a její doprovodné kontejnery

Kroki má modulární architekturu. Brána napsaná v Javě, na Vert.x, přijímá každý požadavek a směruje ho ke správné knihovně. Povinný je jen obraz yuzutech/kroki: dokumentace uvádí, že podle vašich diagramů může stačit.

ObrazCo vykreslujePovinný
yuzutech/krokiBránu a k tomu ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML a C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom a WireVizAno
yuzutech/kroki-mermaidMermaid: vývojové diagramy, sekvenční diagramy a Ganttovy diagramyNe
yuzutech/kroki-bpmnBPMN, pomocí bpmn-jsNe
yuzutech/kroki-excalidrawExcalidraw, styl kreslený od rukyNe
yuzutech/kroki-diagramsnetdiagrams.net, zatím experimentálníNe

Dimenzování serveru

Dokumentace neuvádí žádné číslo pro paměť ani CPU. Říká ale, co zatěžuje nejvíc: doprovodné kontejnery Mermaid, BPMN, Excalidraw a diagrams.net vykreslují každý diagram v prohlížeči Chromium bez grafického rozhraní (headless). Aby nával převodů nepřekročil paměť kontejneru, každý z nich omezuje počet současných vykreslení: ve výchozím nastavení 6 pro Mermaid, BPMN a diagrams.net, 4 pro Excalidraw. Další požadavky čekají ve frontě, až na ně přijde řada.

Na Managed VPS nám stačí popsat vaše diagramy, doprovodné kontejnery, které potřebují, a očekávaný provoz, a doporučíme vám vhodnou velikost.

Instalace pomocí Docker Compose

Dokumentace doporučuje kontejnery, Docker nebo Podman, abyste nemuseli každou knihovnu instalovat ručně. Na serveru s nainstalovaným Dockerem vytvořte složku a vložte do ní tento compose.yaml, převzatý z dokumentace:

compose.yaml
services:
  kroki:
    image: yuzutech/kroki:0.36.0
    restart: unless-stopped
    depends_on:
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "127.0.0.1:8000:8000"
    # If you mount /tmp yourself, keep the exec option
    tmpfs:
      - /tmp:exec
  mermaid:
    image: yuzutech/kroki-mermaid:0.36.0
    restart: unless-stopped
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn:0.36.0
    restart: unless-stopped
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw:0.36.0
    restart: unless-stopped
    expose:
      - "8004"
Terminál
docker compose up -d

Pro diagrams.net, zatím experimentální, přidává README čtvrtý doprovodný kontejner. Přidejte tuto službu a proměnnou KROKI_DIAGRAMSNET_HOST=diagramsnet do sekce environment služby kroki:

compose.yaml, služba k přidání
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Kontrola, že vše odpovídá

Ze serveru vrací cesta /health stav brány a verze knihoven, které obsahuje. Další dva požadavky vykreslí diagram GraphViz přes bránu a poté diagram Mermaid přes jeho doprovodný kontejner:

Terminál, na serveru
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/graphviz/svg --data-raw 'digraph G {Hello->World}'
curl http://127.0.0.1:8000/mermaid/svg --data-raw 'graph TD; A-->B'

Bez Dockeru: samostatný soubor jar

Druhou cestou z dokumentace je samostatný server, zveřejněný na stránce vydání repozitáře jako kroki-standalone-server-v0.36.0.jar. Vyžaduje Javu 21 nebo novější a neobsahuje žádné knihovny diagramů: každá se instaluje zvlášť a její cesta se nastavuje proměnnou, například KROKI_DOT_BIN_PATH, pokud spustitelný soubor není v PATH. Pro adresu naslouchání dejte přednost KROKI_LISTEN, protože dokumentace konfigurace ohlašuje odstranění KROKI_PORT:

Terminál
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar

Konfigurace: proměnné, žádné účty, žádná databáze

Kroki nemá stránku správy, uživatelské účty ani databázi: jeho konfiguraci tvoří sada proměnných prostředí, u souboru jar systémové vlastnosti Javy. V Docker Compose patří do bloku environment příslušné služby a poté docker compose up -d kontejner znovu vytvoří. Nastavení nejdůležitější pro server:

ProměnnáVýchozí hodnotaK čemu slouží
KROKI_SAFE_MODEsecureÚroveň zabezpečení, popsaná níže
KROKI_LISTENVšechna rozhraní, port 8000Adresa a port naslouchání; přijímá také soket UNIX, unix:// následované cestou
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Kde brána najde jednotlivé doprovodné kontejnery; odpovídající proměnné _PORT nastavují port a KROKI_DIAGRAMSNET_HOST slouží pro diagrams.net
KROKI_COMMAND_TIMEOUT5 sekundNejdelší čekání na spustitelný soubor diagramu, například dot
KROKI_CONVERT_TIMEOUT20 sekundNejdelší čekání na knihovnu v Javě, například PlantUML
KROKI_DELEGATE_TIMEOUT_MS30 000Nejdelší čekání na doprovodný kontejner, v milisekundách
KROKI_MAX_URI_LENGTH4 096Délka URL přijímaná pro GET, nad kterou Kroki odpoví kódem 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'Hlavička Content-Security-Policy odesílaná s každou odpovědí
KROKI_CORS_ALLOWED_HEADERSŽádné dalšíDalší hlavičky povolené pro volání z jiného webu

Diagramy Excalidraw vytvářejí dlouhé URL. Pokud KROKI_MAX_URI_LENGTH zvýšíte, dokumentace doporučuje zůstat nejvýše u 8 192 znaků, i když většina prohlížečů přijme v tagu <img> víc. U největších diagramů nese požadavek POST zdrojový text v těle, a ne v URL.

Kroki ke svému provozu nepotřebuje žádný tajný údaj. Obsahují ho dvě volitelná nastavení: token KROKI_COMPANION_REGISTRATION_TOKEN, užitečný, pokud zapnete registraci doprovodných kontejnerů třetích stran, o níž pojednává část o ochraně, a soukromý klíč certifikátu, pokud HTTPS svěříte přímo Kroki. Uchovávejte je mimo jakýkoli repozitář kódu.

HTTPS: reverzní proxy

Brána poskytuje své API přes HTTP. Reverzní proxy před ní naslouchá na portech 80 a 443, získá certifikát Let’s Encrypt, šifruje provoz a předává ho do Kroki na 127.0.0.1:8000. Právě na ní se také filtruje přístup, jak ukazuje další část.

S Caddy

Caddy sám získá a obnovuje certifikát pro zadaný název a jeho direktiva reverse_proxy předává hlavičky X-Forwarded-For, X-Forwarded-Proto a X-Forwarded-Host bez dalšího nastavení:

Caddyfile
diagrams.example.com {
	encode gzip
	reverse_proxy 127.0.0.1:8000
}

S Nginx

Tento blok serveru naslouchá na portu 80, aby mohl Certbot nastavit HTTPS. Dva limity Nginx se potkávají s limity Kroki: tělo požadavku větší než 1 MB se ve výchozím nastavení odmítne kódem 413, což upravuje client_max_body_size pro velké diagramy odesílané metodou POST; řádek požadavku delší než 8 KB dostane kód 414, což upravuje large_client_header_buffers, pokud KROKI_MAX_URI_LENGTH zvýšíte nad tuto hodnotu.

Blok Nginx
server {
    listen 80;
    listen [::]:80;
    server_name diagrams.example.com;

    client_max_body_size 1m;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:8000;
    }
}
Terminál
sudo nginx -t
sudo certbot --nginx

HTTPS bez proxy

Dokumentace popisuje také šifrování přímo v Kroki: KROKI_SSL=true, s certifikátem a soukromým klíčem ve formátu PEM, jako text přes KROKI_SSL_CERT a KROKI_SSL_KEY, nebo jako soubory přes KROKI_SSL_CERT_PATH a KROKI_SSL_KEY_PATH. Obnova certifikátu se pak provádí ručně, zatímco s proxy se o ni Caddy nebo Certbot postarají samy.

Ochrana instance otevřené do internetu

Kroki nemá ověřování: kdokoli, kdo se dostane k API, ho může nechat vykreslovat diagramy. Jeho ochrana proto stojí na třech věcech popsaných v dokumentaci a v poznámkách k vydání: na režimu zabezpečení, na limitech velikosti a času a na tom, co propustí proxy. Začněte tím, že si ujasníte, kdo se k vašemu serveru potřebuje dostat.

Kdo volá váš server?

Režim zabezpečení

KROKI_SAFE_MODE nastavuje tři úrovně, z nichž každá zahrnuje omezení té předchozí. Dokumentace vysvětluje, že některé knihovny umějí číst soubory nebo URL, například direktivy !include v PlantUML, a že Kroki, který jejich kód nekontroluje, takový přístup ve výchozím nastavení blokuje. Vybízí každého, kdo provozuje server, aby zvolil úroveň odpovídající svému použití.

ÚroveňCo dělá
SECURE, výchozíZabrání jakémukoli pokusu o čtení souborů ze souborového systému nebo zdrojů ze sítě
SAFESpoléhá na očištění požadavků, které provádí vlastní bezpečný režim každé knihovny
UNSAFEVypne všechny bezpečnostní funkce

Na veřejné instanci ponechte SECURE. Hlavička Content-Security-Policy, odesílaná ve výchozím nastavení od verze 0.36.0, tuto obranu doplňuje: skript propašovaný do SVG se na původu (origin) Kroki nespustí, ani když se obrázek otevře přímo.

Limity velikosti a času

Časové limity z tabulky konfigurace ohraničují každý převod. Doprovodné kontejnery přidávají vlastní, navržené proti vyčerpání prostředků:

Omezení přístupu na proxy

Když Kroki volá jen váš publikační řetězec, nejjednodušší je přijímat pouze jeho IP adresu. V Caddy vybere matcher remote_ip ostatní adresy a respond jim pošle kód 403:

Caddyfile
diagrams.example.com {
	@external not remote_ip 203.0.113.10
	respond @external 403
	reverse_proxy 127.0.0.1:8000
}

V Nginx dělají totéž direktivy allow a deny bloku location, přičemž platí první odpovídající pravidlo:

Blok Nginx, uvnitř location /
allow 203.0.113.10;
deny all;

Druhou cestou je základní ověřování na proxy: basic_auth v Caddy, jehož heslo se hashuje příkazem caddy hash-password, nebo auth_basic a soubor vytvořený pomocí htpasswd v Nginx. Hodí se pro klienty, kteří přihlašovací údaje posílají s každým voláním, jako curl -u; u publikačního řetězce dokumentace ověřte, že je jeho nástroj umí předávat. Pro instanci, která zůstává veřejná, může Nginx také omezit počet požadavků na IP adresu modulem limit_req, nastaveným podle počtu diagramů na vašich stránkách.

Doprovodné kontejnery třetích stran

Kroki může hostit doprovodné kontejnery třetích stran, které se registrují přes API /services. Toto zjišťování je ve výchozím nastavení vypnuté a v režimu SECURE zůstává vypnuté vždy. Pokud ho zapnete pomocí KROKI_ENABLE_COMPANION_DISCOVERY=true, dokumentace žádá ponechat /services v důvěryhodné síti a důrazně doporučuje token KROKI_COMPANION_REGISTRATION_TOKEN: bez něj Kroki při startu upozorní, že doprovodný kontejner může zaregistrovat kterýkoli klient brány.

Připojení Asciidoctoru, MkDocs a dalších nástrojů

Asciidoctor Kroki a plugin MkDocs ve výchozím nastavení míří na https://kroki.io. Stačí jim URL vašeho serveru, včetně předpony https://.

Asciidoctor a Antora

Rozšíření Asciidoctor Kroki čte atribut kroki-server-url, v hlavičce dokumentu, na příkazovém řádku nebo v playbooku Antora. Přidejte kroki-fetch-diagram, aby se obrázky stáhly při sestavení, místo aby HTML odkazovalo na váš server; tato volba vyžaduje bezpečnostní režim Asciidoctoru server nebo nižší.

Hlavička dokumentu AsciiDoc
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

Plugin mkdocs-kroki-plugin čte server_url, jehož výchozí hodnotou je proměnná prostředí KROKI_SERVER_URL. S http_method: POST se obrázky ukládají vedle každé stránky v sestaveném webu a mezi dvěma sestaveními se uchovávají v mezipaměti:

mkdocs.yml
plugins:
  - kroki:
      server_url: https://diagrams.example.com
      http_method: POST

Další integrace

Stránka dokumentace o nástrojích třetích stran uvádí také GitLab, který vykresluje diagramy Kroki v Markdownu, AsciiDocu, reST a Textile, dále Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, rozšíření pro Visual Studio Code a IntelliJ a Kroki.jl pro Julii. Funguje i jakýkoli HTTP klient, jako v tomto příkladu z dokumentace:

Terminál
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'

Zálohy: konfigurace, žádná data

Kroki je bezstavový: mezi dvěma požadavky si nic neuchovává a po restartu zmizí i registr doprovodných kontejnerů třetích stran. Zdrojové texty vašich diagramů žijí v repozitářích dokumentace a jejich obrázky v sestavených webech. Na serveru Kroki se zálohuje jeho konfigurace:

PoložkaCo obsahujeZálohovat
compose.yamlObrazy, jejich tagy a proměnné KROKI_*Ano
Soubor .env, pokud existujeProměnné držené mimo compose.yaml, například token nebo certifikátAno, na bezpečném místě
Konfigurace proxyCaddyfile nebo blok Nginx a soubor s heslyAno
Obrazy DockerSamotný softwareNe: docker compose pull je stáhne znovu
Terminál, ve složce se souborem compose.yaml
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile

Seznam přizpůsobte své proxy, po každé změně konfigurace vytvořte novou kopii a odešlete ji mimo server. Uložená na jeho disku je také součástí jeho nočních záloh. Obnova znamená vrátit tyto soubory na místo a spustit docker compose up -d.

Aktualizace

S připnutými tagy změňte verzi čtyř obrazů v compose.yaml a poté, z jeho složky:

Terminál
docker compose pull
docker compose up -d

Kroki se řídí sémantickým verzováním a každá verze zveřejňuje své změny v CHANGELOG.md a na své stránce vydání. Přečtěte si je před aktualizací, zejména jejich část „Security“: verze 0.35.0 z 5. listopadu 2026 a 0.36.0 z 9. listopadu 2026 opravují vzdálené spuštění kódu přes diagramy Bytefield a TikZ, zranitelnosti XSS v GoAT a DBML a podvržení požadavků na straně serveru přes BlockDiag a doprovodné kontejnery. Na otevřené instanci tyto verze nasaďte bez odkladu.

Verze 0.36.0 přidává také výchozí hlavičku Content-Security-Policy a engine rozvržení TALA pro D2. Pro ruční instalaci dokumentuje Javu 21 jako minimální verzi.

Kdo co dělá na Managed VPS

Vlastní hosting vyžaduje, abyste kromě aplikace udržovali i server. Na Managed VPS se serveru ujímají naše týmy a vaši instanci proaktivně sledují; Kroki zůstává vaším softwarem, s jeho konfigurací a doprovodnými kontejnery.

TémaNaše týmyVy
ServerAktualizace systému a zabezpečení, včetně zásahů na serveruOkamžik, který vyhovuje vašemu provozu
DohledServer sledovaný 24 hodin denně, 7 dní v týdnu, se zásahem bez čekání na vaše voláníČtení protokolů vaší instance
KrokiProaktivní sledování: chyby, zpomalení, paměť doprovodných kontejnerů a místo na disku zachycené, doporučená opravaJeho instalace, aktualizace a nastavení, které zapracujete vy nebo váš AI asistent
Diagramy a přístupServer, který je vykresluje, hlídaný a zálohovanýRežim zabezpečení, doprovodné kontejnery, limity a pravidla přístupu na proxy
ZálohyKaždou noc, šifrované a uchovávané mimo stroj; obnova v ceněKopie vaší konfigurace uchovávané jinde a žádost o obnovu, když ji potřebujete
MigraceVáš stávající server přenesen zdarmaOkamžik přepnutí

Pokud dáváte přednost tomu, aby naše týmy zasáhly přímo v aplikaci, tato služba se účtuje po hodinách nebo paušálem, s cenovou nabídkou sdělenou před zásahem.

Kroki na serveru, o který se staráme za vás

S Managed VPS od Simafri udržují naše týmy server vaší instance Kroki aktuální, hlídají ho ve dne i v noci a zasahují bez čekání na vaše volání; vaši instanci také proaktivně sledují a doporučí vám užitečné opravy, které zapracujete vy nebo váš AI asistent. Zálohy se každou noc šifrují a uchovávají mimo stroj, jejich obnova je v ceně a migrace vašeho stávajícího serveru je zdarma.

Objevit Managed VPS

Časté otázky

Je Kroki pro firmu zdarma?

Ano. Kroki je pod licencí MIT: můžete ho ve firmě používat, upravovat a dále šířit, aniž byste kupovali licenci, pokud zachováte jeho upozornění o autorských právech. Zbývají náklady na server, na kterém běží.

Potřebuji doprovodné kontejnery Kroki?

Jen pro diagramy, které vykreslují. Obraz yuzutech/kroki stačí pro PlantUML, GraphViz, D2, Structurizr a většinu formátů. Mermaid, BPMN, Excalidraw a diagrams.net potřebují každý svůj doprovodný kontejner, připojený přes KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST nebo KROKI_DIAGRAMSNET_HOST.

Jak nainstalovat Kroki pomocí Docker Compose?

Vytvořte compose.yaml s obrazem yuzutech/kroki, jeho portem 8000 publikovaným na 127.0.0.1 a doprovodnými kontejnery, které potřebujete, například yuzutech/kroki-mermaid, připojenými přes proměnné KROKI_*_HOST. Spusťte docker compose up -d, zkontrolujte /health a potom před port 8000 umístěte reverzní proxy s HTTPS.

Má Kroki účet správce?

Ne, Kroki nemá účty, stránku správy ani databázi. Jeho konfiguraci tvoří sada proměnných prostředí KROKI_* a přístup k API se řídí na reverzní proxy, podle IP adresy nebo základním ověřováním.

Jak ochránit veřejnou instanci Kroki?

Ponechte režim SECURE, zapnutý ve výchozím nastavení, který knihovnám brání číst soubory nebo přistupovat k síti. Nechte na místě časové limity a limity velikosti, aktualizujte, jakmile nová verze opraví zranitelnost, a pokud Kroki volá jen váš publikační řetězec, přijímejte na proxy pouze jeho adresu.

Jak používat svůj server Kroki s Asciidoctorem nebo MkDocs?

V Asciidoctoru nastavte atribut kroki-server-url na URL svého serveru a kroki-fetch-diagram, aby se obrázky stáhly při sestavení. V MkDocs nastavte server_url v konfiguraci pluginu kroki a http_method: POST, aby se obrázky ukládaly spolu s webem.

Co zálohovat na serveru Kroki?

Jen jeho konfiguraci: compose.yaml, případný soubor .env a konfiguraci reverzní proxy. Kroki neuchovává žádná data a jeho obrazy Docker se znovu stáhnou příkazem docker compose pull.

Pokrývá Managed VPS i Kroki?

Managed VPS pokrývá server: systém, zabezpečení, dohled a zálohy. Naše týmy také proaktivně sledují vaši instanci a doporučí vám užitečné opravy, které zapracujete vy. Zásah v samotné aplikaci se účtuje po hodinách nebo paušálem.

Zdroje a oficiální dokumentace

Kontaktujte nás