At hoste Kroki på en Managed VPS betyder, at du renderer dine PlantUML-, Mermaid-, GraphViz-, D2-, BPMN- eller Excalidraw-diagrammer på en maskine, der er din egen, og som vores teams holder opdateret og overvåger dag og nat. Kroki er fri software under MIT-licensen. Denne guide følger den officielle dokumentation: gatewayen og dens følgecontainere, installation med Docker Compose, konfiguration, HTTPS, beskyttelse af en offentlig instans, tilkobling af Asciidoctor og MkDocs, backup og opdateringer.
Af Simon Vasconcelos Lee
Udgivet den 20. november 2026Læsetid: 14 minutter
yuzutech/kroki.KROKI_*_HOST: Docker Compose starter dem sammen.SECURE, som forhindrer det i at læse filer eller netværket; adgangen til en offentlig instans styres i reverse proxyen.compose.yaml og proxyens, og opdatér derefter med docker compose pull, efter at have læst hver udgivelsesnote.Kroki tilbyder et samlet HTTP-API, der modtager et diagram beskrevet som tekst og returnerer et billede. Din dokumentation, din wiki eller din kodeplatform sender diagrammets kilde; Kroki svarer med en SVG og, afhængigt af diagramtypen, en PNG, en PDF eller en JPEG. Dets README nævner BlockDiag, BPMN, Bytefield, C4 med PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom og WireViz.
/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000. En webside viser det så som ethvert andet billede./graphviz/svg, eller i JSON-bodyen.Kroki-Diagram-Options-*.Dokumentationen til Asciidoctor Kroki-udvidelsen giver tre grunde til at køre din egen server frem for den offentlige instans kroki.io: en virksomhedsfirewall, der blokerer den, forsinkelsen, når du er langt fra denne europæiske instans, og fortroligheden, når diagrammernes kilder skal blive inden for din infrastruktur.
Kroki udgives under MIT-licensen. Den giver gratis ret til at bruge, kopiere, ændre, sammenflette, udgive, distribuere, underlicensere og sælge kopier af softwaren. Du kan altså køre den for din virksomhed, dit team eller dine kunder uden at købe en licens.
Den eneste betingelse er at beholde copyrightmeddelelsen og licensteksten i alle kopier eller væsentlige dele af softwaren. Teksten leverer softwaren «som den er», uden garanti. De diagrambiblioteker, som Kroki leveres med, beholder hver deres egen licens.
Kroki har en modulær arkitektur. En gateway skrevet i Java, på Vert.x, modtager hver forespørgsel og sender den videre til det rette bibliotek. Kun imaget yuzutech/kroki er påkrævet: dokumentationen bemærker, at det, afhængigt af dine diagrammer, kan være nok.
| Image | Hvad det renderer | Påkrævet |
|---|---|---|
yuzutech/kroki | Gatewayen, samt ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML og C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom og WireViz | Ja |
yuzutech/kroki-mermaid | Mermaid: flowcharts, sekvens- og Gantt-diagrammer | Nej |
yuzutech/kroki-bpmn | BPMN, med bpmn-js | Nej |
yuzutech/kroki-excalidraw | Excalidraw, den håndtegnede stil | Nej |
yuzutech/kroki-diagramsnet | diagrams.net, stadig eksperimentel | Nej |
Dokumentationen opgiver intet tal for hukommelse eller CPU. Den siger til gengæld, hvad der vejer mest: følgecontainerne til Mermaid, BPMN, Excalidraw og diagrams.net renderer hvert diagram i en Chromium-browser uden brugerflade. For at en bølge af konverteringer ikke skal overskride containerens hukommelse, begrænser hver af dem sine samtidige renderinger: som standard 6 for Mermaid, BPMN og diagrams.net, 4 for Excalidraw. Yderligere forespørgsler venter på deres tur i en kø.
yuzutech/kroki 0.36.0 omkring 1 GB komprimeret. Kroki skriver ingen data: det gemmer intet mellem to forespørgsler.amd64 og arm64.depends_on og KROKI_*_HOST.På en Managed VPS fortæller du os om dine diagrammer, de følgecontainere, de kræver, og den trafik, du forventer, og vi anbefaler den størrelse, der passer.
Dokumentationen anbefaler containere, Docker eller Podman, så du slipper for at installere hvert bibliotek i hånden. Opret en mappe på en server med Docker installeret, og læg denne compose.yaml i den, hentet fra dokumentationen:
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"
docker compose up -d
127.0.0.1: dette er den første ændring i forhold til dokumentationens eksempel, som publicerer 8000:8000. Kroki lytter som standard på alle grænseflader, og Docker publicerer en port på alle serverens adresser, når der ikke angives nogen. Her kan API’et kun nås gennem reverse proxyen.expose: den bliver på det interne Compose-netværk, hvor gatewayen når dem via tjenestens navn. Variablerne KROKI_MERMAID_HOST, KROKI_BPMN_HOST og KROKI_EXCALIDRAW_HOST angiver dette navn; deres standardporte, 8002, 8003 og 8004, behøver ikke at gentages.0.36.0 er den anden ændring: dokumentationens eksempel følger den nyeste version. De fire images udgives sammen under samme tag, som dermed fastlåser en sammenhængende version og gør hver opdatering til et bevidst valg.Til diagrams.net, stadig eksperimentel, tilføjer README’en en fjerde følgecontainer. Tilføj denne tjeneste, og variablen KROKI_DIAGRAMSNET_HOST=diagramsnet i environment for kroki:
diagramsnet:
image: yuzutech/kroki-diagramsnet:0.36.0
restart: unless-stopped
expose:
- "8005"
Fra serveren returnerer ruten /health gatewayens status og versionerne af de biblioteker, den leveres med. De to næste forespørgsler renderer et GraphViz-diagram gennem gatewayen og derefter et Mermaid-diagram gennem dens følgecontainer:
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'
Dokumentationens anden vej er den selvstændige server, udgivet på repositoriets udgivelsesside som kroki-standalone-server-v0.36.0.jar. Den kræver Java 21 eller nyere og indeholder ingen diagrambiblioteker: hvert enkelt installeres for sig, og dets sti angives med en variabel som KROKI_DOT_BIN_PATH, når programmet ikke ligger i PATH. Brug helst KROKI_LISTEN til lytteadressen, da konfigurationsdokumentationen varsler, at KROKI_PORT vil blive fjernet:
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar
Kroki har hverken administrationsside, brugerkonti eller database: dets konfiguration er et sæt miljøvariabler, eller Java-systemegenskaber med jar-filen. I Docker Compose står de i blokken environment for den pågældende tjeneste, og docker compose up -d genskaber derefter containeren. De indstillinger, der betyder mest for en server:
| Variabel | Standard | Hvad den gør |
|---|---|---|
KROKI_SAFE_MODE | secure | Sikkerhedsniveauet, beskrevet nedenfor |
KROKI_LISTEN | Alle grænseflader, port 8000 | Lytteadressen og porten; accepterer også en UNIX-socket, unix:// efterfulgt af en sti |
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST | 127.0.0.1 | Hvor gatewayen når hver følgecontainer; de tilsvarende variabler _PORT angiver porten, og KROKI_DIAGRAMSNET_HOST dækker diagrams.net |
KROKI_COMMAND_TIMEOUT | 5 sekunder | Den længste ventetid på et diagramprogram, som dot |
KROKI_CONVERT_TIMEOUT | 20 sekunder | Den længste ventetid på et Java-bibliotek, som PlantUML |
KROKI_DELEGATE_TIMEOUT_MS | 30.000 | Den længste ventetid på en følgecontainer, i millisekunder |
KROKI_MAX_URI_LENGTH | 4.096 | Den URL-længde, der accepteres med GET, og over hvilken Kroki svarer 414 |
KROKI_CONTENT_SECURITY_POLICY | script-src 'none'; object-src 'none' | Headeren Content-Security-Policy, der sendes med hvert svar |
KROKI_CORS_ALLOWED_HEADERS | Ingen ekstra | Yderligere headere, der tillades ved kald fra et andet website |
Excalidraw-diagrammer giver lange URL’er. Hvis du hæver KROKI_MAX_URI_LENGTH, anbefaler dokumentationen at holde sig på 8.192 tegn eller derunder, selv om de fleste browsere accepterer mere i et tag <img>. Til de største diagrammer bærer en POST-forespørgsel kilden i bodyen frem for i URL’en.
Kroki behøver ingen hemmelighed for at køre. To valgfrie indstillinger indeholder en: tokenet KROKI_COMPANION_REGISTRATION_TOKEN, nyttigt hvis du aktiverer registrering af følgecontainere fra tredjeparter, omtalt i afsnittet om beskyttelse, og den private nøgle til et certifikat, hvis du lader Kroki selv håndtere HTTPS. Hold dem ude af ethvert kode-repository.
Gatewayen leverer sit API over HTTP. En reverse proxy foran den lytter på portene 80 og 443, henter certifikatet fra Let’s Encrypt, krypterer trafikken og sender den videre til Kroki på 127.0.0.1:8000. Det er også her, adgangen filtreres, som det næste afsnit viser.
Caddy henter og fornyer selv certifikatet for det angivne navn, og dens direktiv reverse_proxy videregiver headerne X-Forwarded-For, X-Forwarded-Proto og X-Forwarded-Host uden ekstra indstilling:
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
Denne serverblok lytter på port 80, så Certbot kan sætte HTTPS op. To af Nginx’ grænser møder Krokis: en request-body over 1 MB afvises som standard med en 413, hvilket client_max_body_size justerer for store diagrammer sendt med POST; en forespørgselslinje over 8 KB får en 414, hvilket large_client_header_buffers justerer, hvis du hæver KROKI_MAX_URI_LENGTH ud over det.
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;
}
}
sudo nginx -t
sudo certbot --nginx
Dokumentationen beskriver også kryptering ved Kroki selv: KROKI_SSL=true, med certifikatet og den private nøgle i PEM-format, som tekst via KROKI_SSL_CERT og KROKI_SSL_KEY eller som filer via KROKI_SSL_CERT_PATH og KROKI_SSL_KEY_PATH. Fornyelsen af certifikatet sker så i hånden, hvor Caddy eller Certbot selv klarer den foran en proxy.
Kroki har ingen godkendelse: enhver, der når API’et, kan få det til at rendere diagrammer. Dets beskyttelse hviler derfor på tre ting, beskrevet i dokumentationen og udgivelsesnoterne: sikkerhedstilstanden, grænserne for størrelse og tid, og det, proxyen lukker igennem. Begynd med at finde ud af, hvem der skal kunne nå din server.
kroki-fetch-diagram, MkDocs-pluginnet med http_method: POST: billederne gemmes sammen med websitet, og Kroki-serveren behøver ikke længere at være offentlig.KROKI_SAFE_MODE fastlægger tre niveauer, der hver omfatter det foregåendes begrænsninger. Dokumentationen forklarer, at nogle biblioteker kan læse filer eller URL’er, som PlantUML’s direktiver !include, og at Kroki, som ikke gennemgår deres kode, som standard blokerer den slags adgang. Den opfordrer alle, der driver en server, til at vælge det niveau, der passer til deres brug.
| Niveau | Hvad det gør |
|---|---|
SECURE, standarden | Forhindrer ethvert forsøg på at læse filer fra filsystemet eller ressourcer fra netværket |
SAFE | Stoler på den rensning af forespørgsler, som hvert biblioteks egen sikre tilstand udfører |
UNSAFE | Slår alle sikkerhedsfunktioner fra |
SECURE afvises dets !include og !includeurl, og dets sikkerhedsprofil er SANDBOX. I SAFE bliver profilen ALLOWLIST, og KROKI_PLANTUML_ALLOWLIST_URL eller KROKI_PLANTUML_ALLOWLIST_PATH angiver, hvad der må indlæses.UNSAFE indlæser deres browser kun lokale ressourcer. For at tillade en intern billedbank uden at forlade denne tilstand tilbyder dokumentationen KROKI_ALLOWED_ORIGINS, eller formen pr. følgecontainer som KROKI_MERMAID_ALLOWED_ORIGINS, på følgecontainerens container.UNSAFE: ingen !include for Structurizr, intet eksternt billede for BlockDiag, ingen fillæsning for Lini.KROKI_STRUCTURIZR_SAFE_MODE eller KROKI_MERMAID_SAFE_MODE, frem for at sænke niveauet for hele serveren.Behold SECURE på en offentlig instans. Headeren Content-Security-Policy, der sendes som standard siden 0.36.0, fuldender dette forsvar: et script, der er smuglet ind i en SVG, kører ikke på Krokis oprindelse, heller ikke når billedet åbnes direkte.
Timeouts i konfigurationstabellen afgrænser hver konvertering. Følgecontainerne tilføjer deres egne, designet mod udtømning af ressourcer:
KROKI_MERMAID_MAX_TEXT_SIZE) eller med mere end 500 kanter med en 400, og afbryder en rendering efter 10 sekunder med en 408. Disse grænser kan ikke tilsidesættes via en forespørgsels parametre.KROKI_MAX_BODY_SIZE).Når kun din udgivelseskæde kalder Kroki, er det enkleste at acceptere dens IP-adresse alene. Med Caddy udvælger matcheren remote_ip de øvrige adresser, og respond sender dem en 403:
diagrams.example.com {
@external not remote_ip 203.0.113.10
respond @external 403
reverse_proxy 127.0.0.1:8000
}
Med Nginx klarer direktiverne allow og deny i blokken location samme opgave, hvor den første regel, der passer, gælder:
allow 203.0.113.10;
deny all;
Proxyens basale godkendelse er den anden vej: basic_auth med Caddy, hvis adgangskode hashes med caddy hash-password, eller auth_basic og en fil oprettet med htpasswd med Nginx. Den passer til klienter, der sender loginoplysningerne med hvert kald, som curl -u; til en dokumentationskæde skal du kontrollere, at dens værktøj kan videregive dem. For en instans, der forbliver offentlig, kan Nginx også begrænse antallet af forespørgsler pr. IP-adresse med sit modul limit_req, afstemt efter antallet af diagrammer på dine sider.
Kroki kan huse følgecontainere fra tredjeparter, der registrerer sig via API’et /services. Denne opdagelse er slået fra som standard og forbliver altid slået fra i tilstanden SECURE. Hvis du aktiverer den med KROKI_ENABLE_COMPANION_DISCOVERY=true, beder dokumentationen dig holde /services på et betroet netværk og anbefaler kraftigt tokenet KROKI_COMPANION_REGISTRATION_TOKEN: uden det advarer Kroki ved opstart om, at enhver klient af gatewayen kan registrere en følgecontainer.
Asciidoctor Kroki og MkDocs-pluginnet peger som standard på https://kroki.io. De behøver blot din servers URL, med præfikset https://.
Asciidoctor Kroki-udvidelsen læser attributten kroki-server-url i dokumentets header, på kommandolinjen eller i Antora-playbooken. Tilføj kroki-fetch-diagram for at hente billederne under buildet i stedet for at lade HTML’en pege på din server; denne indstilling kræver en Asciidoctor-sikkerhedstilstand på server eller lavere.
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:
Pluginnet mkdocs-kroki-plugin læser server_url, som standard miljøvariablen KROKI_SERVER_URL. Med http_method: POST gemmes billederne ved siden af hver side i det byggede website og caches mellem to builds:
plugins:
- kroki:
server_url: https://diagrams.example.com
http_method: POST
Dokumentationens side om tredjepartsværktøjer nævner også GitLab, som renderer Kroki-diagrammer i Markdown, AsciiDoc, reST og Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, udvidelser til Visual Studio Code og IntelliJ samt Kroki.jl til Julia. Enhver HTTP-klient virker også, som i dette eksempel fra dokumentationen:
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'
Kroki er tilstandsløs: det gemmer intet mellem to forespørgsler, og selv registret over følgecontainere fra tredjeparter er væk efter en genstart. Kilderne til dine diagrammer ligger i dine dokumentationsrepositorier, og deres billeder i dine byggede websites. På Kroki-serveren er det konfigurationen, der tages backup af:
| Element | Hvad det indeholder | Tag backup |
|---|---|---|
compose.yaml | Imagene, deres tags og variablerne KROKI_* | Ja |
Filen .env, hvis den findes | Variabler holdt uden for compose.yaml, som et token eller et certifikat | Ja, et sikkert sted |
| Proxyens konfiguration | Caddyfile eller Nginx-blokken, og adgangskodefilen | Ja |
| Docker-images | Selve softwaren | Nej: docker compose pull henter dem igen |
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile
Tilpas listen til din proxy, lav en ny kopi efter hver ændring af konfigurationen, og send den væk fra serveren. Gemt på dens disk indgår den også i dens natlige backup. En gendannelse består i at lægge disse filer tilbage og køre docker compose up -d.
Med fastlåste tags ændrer du versionen af de fire images i compose.yaml og kører derefter, fra dens mappe:
docker compose pull
docker compose up -d
Kroki følger semantisk versionering, og hver version offentliggør sine ændringer i CHANGELOG.md og på sin udgivelsesside. Læs dem før opdateringen, især deres afsnit «Security»: 0.35.0 fra 5. november 2026 og 0.36.0 fra 9. november 2026 retter fjernkørsel af kode via Bytefield- og TikZ-diagrammer, XSS-sårbarheder i GoAT og DBML samt server-side request forgery via BlockDiag og følgecontainerne. På en åben instans bør disse versioner rulles ud uden at vente.
Version 0.36.0 tilføjer også headeren Content-Security-Policy som standard og layoutmotoren TALA til D2. Til den manuelle installation dokumenterer den Java 21 som minimumsversion.
Selvhosting kræver, at du holder serveren ud over selve applikationen. På en Managed VPS tager vores teams sig af serveren og følger din instans proaktivt; Kroki forbliver din software, med dets konfiguration og dets følgecontainere.
| Emne | Vores teams | Dig |
|---|---|---|
| Serveren | Opdateringer af system og sikkerhed, indgreb på serveren inkluderet | Det tidspunkt, der passer til din drift |
| Overvågningen | Serveren følges døgnet rundt, alle ugens dage, med indgreb uden at vente på dit opkald | Gennemlæsning af din instans' logfiler |
| Kroki | Proaktiv opfølgning: fejl, langsomme svartider, følgecontainernes hukommelse og diskplads opdages, og en rettelse anbefales | Installation, opdateringer og indstillinger, som du gennemfører, selv eller med din AI-assistent |
| Diagrammer og adgang | Den server, der renderer dem, overvåget og sikkerhedskopieret | Sikkerhedstilstanden, følgecontainerne, grænserne og proxyens adgangsregler |
| Backup | Hver nat, krypteret og opbevaret uden for maskinen; gendannelse inkluderet | De kopier af din konfiguration, som du opbevarer andetsteds, og anmodningen om gendannelse, når du får brug for den |
| Migreringen | Din nuværende server flyttes, uden beregning | Tidspunktet for omlægningen |
Hvis du foretrækker, at vores teams griber ind i selve applikationen, faktureres den ydelse pr. time eller som fast pris, med et overslag oplyst før indgrebet.
Med en Managed VPS fra Simafri holder vores teams serveren bag din Kroki-instans opdateret, overvåger den dag og nat og griber ind uden at vente på dit opkald; de følger også din instans proaktivt og anbefaler dig de nyttige rettelser, som du gennemfører, selv eller med din AI-assistent. Backup krypteres hver nat og opbevares uden for maskinen, gendannelsen er inkluderet, og migreringen af din nuværende server sker uden beregning.
Ja. Kroki er under MIT-licensen: du kan bruge, ændre og videredistribuere det i en virksomhed uden at købe en licens, så længe du beholder dets copyrightmeddelelse. Tilbage står prisen for den server, der kører det.
Kun til de diagrammer, de renderer. Imaget yuzutech/kroki er nok til PlantUML, GraphViz, D2, Structurizr og de fleste formater. Mermaid, BPMN, Excalidraw og diagrams.net kræver hver deres følgecontainer, forbundet via KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST eller KROKI_DIAGRAMSNET_HOST.
Opret en compose.yaml med imaget yuzutech/kroki, dets port 8000 publiceret på 127.0.0.1, og de følgecontainere, du har brug for, som yuzutech/kroki-mermaid, forbundet via variablerne KROKI_*_HOST. Kør docker compose up -d, kontrollér /health, og sæt derefter en reverse proxy med HTTPS foran port 8000.
Nej, Kroki har hverken konti, administrationsside eller database. Dets konfiguration er et sæt miljøvariabler KROKI_*, og adgangen til API’et styres i reverse proxyen, efter IP-adresse eller med basal godkendelse.
Behold tilstanden SECURE, der er slået til som standard, og som forhindrer bibliotekerne i at læse filer eller netværket. Lad grænserne for tid og størrelse blive, opdatér, så snart en version retter en sårbarhed, og accepter kun din udgivelseskædes adresse i proxyen, hvis kun den kalder Kroki.
Med Asciidoctor sætter du attributten kroki-server-url til din servers URL, og kroki-fetch-diagram for at hente billederne under buildet. Med MkDocs sætter du server_url i konfigurationen af pluginnet kroki, og http_method: POST for at gemme billederne sammen med websitet.
Kun dets konfiguration: compose.yaml, en eventuel fil .env og reverse proxyens konfiguration. Kroki gemmer ingen data, og dets Docker-images hentes igen med docker compose pull.
En Managed VPS dækker serveren: system, sikkerhed, overvågning og backup. Vores teams følger også din instans proaktivt og anbefaler dig de nyttige rettelser, som du gennemfører. Et indgreb i selve applikationen faktureres pr. time eller som fast pris.
Simafri
Lad os tale om din hjemmeside
Fortæl os om dit projekt med få ord: vi vender hurtigt tilbage til dig.
Tak! Din forespørgsel er sendt. Vi vender tilbage til dig hurtigst muligt.
Foretrækker du e-mail? Skriv til os på support@simafri.com.