Kroki hosten op een Managed VPS: uw diagrammen op uw eigen server

Kroki hosten op een Managed VPS betekent dat u uw PlantUML-, Mermaid-, GraphViz-, D2-, BPMN- of Excalidraw-diagrammen rendert op een machine die van u is, en die ons team bijwerkt en dag en nacht in de gaten houdt. Kroki is vrije software onder de MIT-licentie. Deze gids volgt de officiële documentatie: de gateway en zijn companion-containers, de installatie met Docker Compose, de configuratie, HTTPS, de beveiliging van een openbare instantie, de koppeling met Asciidoctor en MkDocs, back-ups en updates.

Simon Vasconcelos Lee Door Gepubliceerd op 20 november 2026Leestijd: 14 minuten

Alle gidsen

In het kort

  1. Dankzij de MIT-licentie gebruikt, wijzigt en verspreidt u Kroki vrij, in een bedrijf of elders, op voorwaarde dat u de copyrightvermelding behoudt.
  2. Kroki zet een als tekst geschreven diagram via één enkele HTTP-API om in een afbeelding: PlantUML, GraphViz, D2, Structurizr en vele andere zitten in de image yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw en diagrams.net hebben elk hun eigen companion-container nodig, die via de variabelen KROKI_*_HOST met de gateway verbonden is: Docker Compose start ze samen.
  4. Kroki heeft geen accounts en geen database. Het start in de modus SECURE, die het belet bestanden of het netwerk te lezen; de toegang tot een openbare instantie regelt u bij de reverse proxy.
  5. Maak een back-up van de configuratie, compose.yaml en die van de proxy, en werk daarna bij met docker compose pull, na het lezen van elke release-opmerking.

Wat Kroki doet

Kroki biedt een uniforme HTTP-API die een als tekst beschreven diagram ontvangt en een afbeelding teruggeeft. Uw documentatie, uw wiki of uw codeplatform stuurt de bron van het diagram; Kroki antwoordt met een SVG en, afhankelijk van het type diagram, een PNG, een PDF of een JPEG. Zijn README noemt BlockDiag, BPMN, Bytefield, C4 met PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom en WireViz.

De documentatie van de Asciidoctor Kroki-extensie geeft drie redenen om een eigen server te draaien in plaats van de openbare instantie kroki.io: een bedrijfsfirewall die haar blokkeert, de latentie wanneer u ver van die Europese instantie zit, en de vertrouwelijkheid, wanneer de bronnen van de diagrammen binnen uw infrastructuur moeten blijven.

Wat de MIT-licentie toestaat

Kroki wordt gepubliceerd onder de MIT-licentie. Die geeft kosteloos het recht de software te gebruiken, te kopiëren, te wijzigen, samen te voegen, te publiceren, te verspreiden, in sublicentie te geven en kopieën ervan te verkopen. U kunt haar dus draaien voor uw bedrijf, uw team of uw klanten, zonder een licentie te kopen.

De enige voorwaarde is dat u de copyrightvermelding en de tekst van de licentie behoudt in alle kopieën of wezenlijke delen van de software. De tekst levert de software “zoals hij is”, zonder garantie. De diagrambibliotheken die Kroki meelevert, behouden elk hun eigen licentie.

De gateway en zijn companion-containers

Kroki heeft een modulaire architectuur. Een gateway, in Java geschreven, op Vert.x, ontvangt elk verzoek en stuurt het door naar de juiste bibliotheek. Alleen de image yuzutech/kroki is verplicht: de documentatie merkt op dat die, afhankelijk van uw diagrammen, kan volstaan.

ImageWat ze rendertVerplicht
yuzutech/krokiDe gateway, plus ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML en C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom en WireVizJa
yuzutech/kroki-mermaidMermaid: stroomdiagrammen, sequentie- en Gantt-diagrammenNee
yuzutech/kroki-bpmnBPMN, met bpmn-jsNee
yuzutech/kroki-excalidrawExcalidraw, de handgetekende stijlNee
yuzutech/kroki-diagramsnetdiagrams.net, nog experimenteelNee

De server dimensioneren

De documentatie noemt geen cijfer voor geheugen of CPU. Ze zegt wel wat het zwaarst weegt: de companions voor Mermaid, BPMN, Excalidraw en diagrams.net renderen elk diagram in een Chromium-browser zonder interface. Om te voorkomen dat een golf van conversies het geheugen van de container overschrijdt, begrenst elk van hen zijn gelijktijdige renders: standaard 6 voor Mermaid, BPMN en diagrams.net, 4 voor Excalidraw. Verdere verzoeken wachten in een wachtrij op hun beurt.

Vertel ons op een managed VPS over uw diagrammen, de companions die ze nodig hebben en het verkeer dat u verwacht, dan raden wij u de passende grootte aan.

De installatie met Docker Compose

De documentatie raadt containers aan, Docker of Podman, zodat u niet elke bibliotheek met de hand hoeft te installeren. Maak op een server waarop Docker is geïnstalleerd een map aan en zet daarin deze compose.yaml, overgenomen uit de documentatie:

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"
Terminal
docker compose up -d

Voor diagrams.net, nog experimenteel, voegt de README een vierde companion toe. Voeg deze dienst toe, en de variabele KROKI_DIAGRAMSNET_HOST=diagramsnet aan de environment van kroki:

compose.yaml, toe te voegen dienst
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Controleren of alles antwoordt

Vanaf de server geeft de route /health de status van de gateway en de versies van de bibliotheken die hij meelevert. De twee volgende verzoeken renderen een GraphViz-diagram via de gateway, daarna een Mermaid-diagram via zijn companion:

Terminal, op de server
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'

Zonder Docker: de standalone jar

De andere weg van de documentatie is de standalone server, gepubliceerd op de releasepagina van de repository als kroki-standalone-server-v0.36.0.jar. Hij vereist Java 21 of hoger en bevat geen enkele diagrambibliotheek: elke bibliotheek wordt apart geïnstalleerd, en haar pad stelt u in met een variabele zoals KROKI_DOT_BIN_PATH wanneer het programma niet in het PATH staat. Gebruik voor het luisteradres bij voorkeur KROKI_LISTEN, want de configuratiedocumentatie kondigt aan dat KROKI_PORT zal verdwijnen:

Terminal
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar

De configuratie: variabelen, geen accounts, geen database

Kroki heeft geen beheerpagina, geen gebruikersaccounts en geen database: zijn configuratie bestaat uit omgevingsvariabelen, of uit Java-systeemeigenschappen bij de jar. In Docker Compose staan ze in het blok environment van de betreffende dienst, waarna docker compose up -d de container opnieuw aanmaakt. De instellingen die voor een server het meest tellen:

VariabeleStandaardWaarvoor ze dient
KROKI_SAFE_MODEsecureHet beveiligingsniveau, hieronder toegelicht
KROKI_LISTENAlle interfaces, poort 8000Het adres en de poort waarop Kroki luistert; aanvaardt ook een UNIX-socket, unix:// gevolgd door een pad
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Waar de gateway elke companion bereikt; de bijbehorende variabelen _PORT stellen de poort in, en KROKI_DIAGRAMSNET_HOST dient voor diagrams.net
KROKI_COMMAND_TIMEOUT5 secondenDe langste wachttijd op een diagramprogramma, zoals dot
KROKI_CONVERT_TIMEOUT20 secondenDe langste wachttijd op een Java-bibliotheek, zoals PlantUML
KROKI_DELEGATE_TIMEOUT_MS30.000De langste wachttijd op een companion, in milliseconden
KROKI_MAX_URI_LENGTH4.096De URL-lengte die bij GET wordt aanvaard, waarboven Kroki met 414 antwoordt
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'De header Content-Security-Policy die met elk antwoord wordt meegestuurd
KROKI_CORS_ALLOWED_HEADERSGeen extraAanvullende headers die zijn toegestaan voor aanroepen vanaf een andere site

Excalidraw-diagrammen leveren lange URL's op. Verhoogt u KROKI_MAX_URI_LENGTH, dan raadt de documentatie aan op 8.192 tekens of minder te blijven, ook al aanvaarden de meeste browsers meer in een tag <img>. Voor de grootste diagrammen draagt een POST-verzoek de bron in de body in plaats van in de URL.

Kroki heeft geen geheim nodig om te draaien. Twee optionele instellingen bevatten er wel een: het token KROKI_COMPANION_REGISTRATION_TOKEN, nuttig als u de registratie van companions van derden inschakelt, behandeld in het deel over beveiliging, en de privésleutel van een certificaat, als u Kroki zelf HTTPS laat afhandelen. Houd ze buiten elke coderepository.

HTTPS: de reverse proxy

De gateway levert zijn API via HTTP. Een reverse proxy ervoor luistert op de poorten 80 en 443, haalt het certificaat van Let’s Encrypt op, versleutelt het verkeer en geeft het door aan Kroki op 127.0.0.1:8000. Daar wordt ook de toegang gefilterd, zoals het volgende deel laat zien.

Met Caddy

Caddy haalt het certificaat voor de opgegeven naam zelf op en vernieuwt het, en zijn directive reverse_proxy geeft de headers X-Forwarded-For, X-Forwarded-Proto en X-Forwarded-Host door zonder extra instelling:

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

Met Nginx

Dit serverblok luistert op poort 80, zodat Certbot HTTPS kan instellen. Twee grenzen van Nginx raken die van Kroki: een request-body van meer dan 1 MB wordt standaard geweigerd met een 413, wat client_max_body_size aanpast voor grote diagrammen die met POST worden verstuurd; een verzoekregel van meer dan 8 KB krijgt een 414, wat large_client_header_buffers aanpast als u KROKI_MAX_URI_LENGTH daarboven verhoogt.

Nginx-blok
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;
    }
}
Terminal
sudo nginx -t
sudo certbot --nginx

HTTPS zonder proxy

De documentatie beschrijft ook versleuteling door Kroki zelf: KROKI_SSL=true, met het certificaat en de privésleutel in PEM-formaat, als tekst via KROKI_SSL_CERT en KROKI_SSL_KEY, of als bestanden via KROKI_SSL_CERT_PATH en KROKI_SSL_KEY_PATH. Het certificaat vernieuwt u dan met de hand, terwijl Caddy of Certbot dat achter een proxy zelf regelen.

Een instantie beveiligen die open staat voor internet

Kroki heeft geen authenticatie: wie de API bereikt, kan er diagrammen mee laten renderen. Zijn beveiliging rust daarom op drie zaken, beschreven in de documentatie en de release-opmerkingen: de beveiligingsmodus, de grenzen aan grootte en tijd, en wat de proxy doorlaat. Begin met na te gaan wie uw server moet bereiken.

Wie roept uw server aan?

De beveiligingsmodus

KROKI_SAFE_MODE kent drie niveaus, die elk de beperkingen van het vorige omvatten. De documentatie legt uit dat sommige bibliotheken bestanden of URL's kunnen lezen, zoals de directives !include van PlantUML, en dat Kroki, dat hun code niet controleert, zulke toegang standaard blokkeert. Ze vraagt iedereen die een server draait het niveau te kiezen dat bij zijn gebruik past.

NiveauWat het doet
SECURE, de standaardVerhindert elke poging om bestanden van het bestandssysteem of bronnen van het netwerk te lezen
SAFEVertrouwt op het opschonen van verzoeken door de eigen veilige modus van elke bibliotheek
UNSAFESchakelt alle beveiligingsfuncties uit

Houd op een openbare instantie SECURE aan. De header Content-Security-Policy, sinds 0.36.0 standaard meegestuurd, vult die verdediging aan: een script dat in een SVG is gesmokkeld, wordt niet uitgevoerd op de oorsprong van Kroki, ook niet wanneer de afbeelding rechtstreeks wordt geopend.

Grenzen aan grootte en tijd

De time-outs uit de configuratietabel begrenzen elke conversie. De companions voegen er hun eigen grenzen aan toe, ontworpen tegen uitputting van bronnen:

De toegang beperken bij de proxy

Wanneer alleen uw publicatieketen Kroki aanroept, is het eenvoudigst om uitsluitend haar IP-adres toe te laten. Met Caddy selecteert de matcher remote_ip de andere adressen, en stuurt respond hun een 403:

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

Met Nginx doen de directives allow en deny van het blok location hetzelfde werk, waarbij de eerste passende regel geldt:

Nginx-blok, in location /
allow 203.0.113.10;
deny all;

De basisauthenticatie van de proxy is de andere weg: basic_auth met Caddy, waarvan het wachtwoord wordt gehasht met caddy hash-password, of auth_basic en een bestand aangemaakt met htpasswd met Nginx. Ze past bij clients die de inloggegevens bij elke aanroep meesturen, zoals curl -u; controleer voor een documentatieketen of de tool ervan ze kan doorgeven. Voor een instantie die openbaar blijft, kan Nginx ook het aantal verzoeken per IP-adres beperken met zijn module limit_req, afgestemd op het aantal diagrammen op uw pagina's.

Companions van derden

Kroki kan companions van derden opnemen die zich registreren via de API /services. Deze ontdekking staat standaard uit, en blijft in de modus SECURE altijd uit. Schakelt u haar in met KROKI_ENABLE_COMPANION_DISCOVERY=true, dan vraagt de documentatie /services op een vertrouwd netwerk te houden, en raadt ze het token KROKI_COMPANION_REGISTRATION_TOKEN sterk aan: zonder dat token waarschuwt Kroki bij het opstarten dat elke client van de gateway een companion kan registreren.

Asciidoctor, MkDocs en andere tools koppelen

Asciidoctor Kroki en de MkDocs-plugin richten zich standaard op https://kroki.io. Ze hebben alleen de URL van uw server nodig, met het voorvoegsel https://.

Asciidoctor en Antora

De Asciidoctor Kroki-extensie leest het attribuut kroki-server-url, in de kop van het document, op de opdrachtregel of in het Antora-playbook. Voeg kroki-fetch-diagram toe om de afbeeldingen tijdens de build te downloaden in plaats van de HTML naar uw server te laten verwijzen; deze optie vereist een veilige modus van Asciidoctor van server of lager.

Kop van het AsciiDoc-document
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

De plugin mkdocs-kroki-plugin leest server_url, standaard de omgevingsvariabele KROKI_SERVER_URL. Met http_method: POST worden de afbeeldingen naast elke pagina van de gebouwde site opgeslagen, en tussen twee builds in de cache bewaard:

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

Andere integraties

De pagina over tools van derden in de documentatie noemt ook GitLab, dat Kroki-diagrammen rendert in Markdown, AsciiDoc, reST en Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, extensies voor Visual Studio Code en IntelliJ, en Kroki.jl voor Julia. Elke HTTP-client werkt ook, zoals in dit voorbeeld uit de documentatie:

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

De back-ups: configuratie, geen gegevens

Kroki is stateless: het bewaart niets tussen twee verzoeken, en zelfs het register van companions van derden is na een herstart verdwenen. De bronnen van uw diagrammen staan in de repository's van uw documentatie, hun afbeeldingen in uw gebouwde sites. Op de Kroki-server maakt u een back-up van zijn configuratie:

OnderdeelWat het bevatBack-up maken
compose.yamlDe images, hun tags en de variabelen KROKI_*Ja
Bestand .env, indien aanwezigVariabelen die buiten compose.yaml worden gehouden, zoals een token of een certificaatJa, op een veilige plek
Configuratie van de proxyDe Caddyfile of het Nginx-blok, en het wachtwoordbestandJa
Docker-imagesDe software zelfNee: docker compose pull downloadt ze opnieuw
Terminal, in de map van compose.yaml
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile

Pas de lijst aan uw proxy aan, maak na elke wijziging van de configuratie een nieuwe kopie, en stuur die buiten de server. Opgeslagen op zijn schijf, zit ze ook in zijn nachtelijke back-ups. Terugzetten betekent deze bestanden terugplaatsen en docker compose up -d uitvoeren.

De updates

Wijzig met vastgelegde tags de versie van de vier images in compose.yaml, en voer daarna in de map ervan uit:

Terminal
docker compose pull
docker compose up -d

Kroki volgt semantic versioning, en elke versie publiceert haar wijzigingen in CHANGELOG.md en op haar releasepagina. Lees ze voordat u bijwerkt, vooral het deel “Security”: 0.35.0 van 5 november 2026 en 0.36.0 van 9 november 2026 verhelpen het uitvoeren van code op afstand via Bytefield- en TikZ-diagrammen, XSS-lekken in GoAT en DBML, en server-side request forgery via BlockDiag en de companions. Rol deze versies op een open instantie zonder uitstel uit.

Versie 0.36.0 voegt ook de standaardheader Content-Security-Policy en de layout-engine TALA voor D2 toe. Voor de handmatige installatie documenteert ze Java 21 als minimumversie.

Wie doet wat op een managed VPS

Self-hosting vraagt dat u naast de applicatie ook de server beheert. Op een managed VPS neemt ons team de server voor zijn rekening en houdt het uw instantie proactief in de gaten; Kroki blijft uw software, met zijn configuratie en zijn companions.

OnderwerpOns teamU
De serverSysteem- en beveiligingsupdates, ingrepen op de server inbegrepenHet moment dat bij uw activiteit past
De monitoringServer 24 uur per dag en 7 dagen per week bewaakt, met ingrijpen zonder op uw oproep te wachtenHet lezen van de logboeken van uw instantie
KrokiProactief toezicht: fouten, vertragingen, geheugen van de companions en schijfruimte opgespoord, correctie aangeradenDe installatie, de updates en de instellingen, die u toepast, zelf of via uw AI-assistent
De diagrammen en de toegangDe server die ze rendert, bewaakt en geback-uptDe beveiligingsmodus, de companions, de grenzen en de toegangsregels van de proxy
De back-upsElke nacht, versleuteld en buiten de machine bewaard; terugzetten inbegrepenDe kopieën van uw configuratie die u elders bewaart, en het verzoek om terug te zetten, wanneer u dat nodig hebt
De migratieUw huidige server gemigreerd, gratisHet moment van de overschakeling

Wilt u liever dat ons team in de applicatie zelf ingrijpt, dan wordt die dienstverlening per uur of tegen een vast bedrag gefactureerd, met een offerte voordat het werk begint.

Kroki, op een server die voor u wordt beheerd

Met een Managed VPS van Simafri houdt ons team de server van uw Kroki-instantie up-to-date, bewaakt hem dag en nacht en grijpt in zonder op uw oproep te wachten; het houdt ook uw instantie proactief in de gaten en raadt u de nuttige correcties aan, die u toepast, zelf of via uw AI-assistent. De back-ups worden elke nacht versleuteld en buiten de machine bewaard, het terugzetten is inbegrepen, en de migratie van uw huidige server is gratis.

Ontdek Managed VPS

Veelgestelde vragen

Is Kroki gratis voor een bedrijf?

Ja. Kroki valt onder de MIT-licentie: u mag het in een bedrijf gebruiken, wijzigen en verspreiden zonder een licentie te kopen, op voorwaarde dat u de copyrightvermelding behoudt. Wat overblijft, zijn de kosten van de server waarop het draait.

Heb ik de companion-containers van Kroki nodig?

Alleen voor de diagrammen die ze renderen. De image yuzutech/kroki volstaat voor PlantUML, GraphViz, D2, Structurizr en de meeste formaten. Mermaid, BPMN, Excalidraw en diagrams.net hebben elk hun companion nodig, gekoppeld via KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST of KROKI_DIAGRAMSNET_HOST.

Hoe installeer ik Kroki met Docker Compose?

Maak een compose.yaml aan met de image yuzutech/kroki, waarvan poort 8000 op 127.0.0.1 is gepubliceerd, en de companions die u nodig hebt, zoals yuzutech/kroki-mermaid, gekoppeld via de variabelen KROKI_*_HOST. Voer docker compose up -d uit, controleer /health, en zet daarna een reverse proxy met HTTPS voor poort 8000.

Heeft Kroki een beheerdersaccount?

Nee, Kroki heeft geen accounts, geen beheerpagina en geen database. Zijn configuratie bestaat uit omgevingsvariabelen KROKI_*, en de toegang tot de API regelt u bij de reverse proxy, op IP-adres of met basisauthenticatie.

Hoe beveilig ik een openbare Kroki-instantie?

Houd de modus SECURE aan, standaard ingeschakeld, die de bibliotheken belet bestanden of het netwerk te lezen. Laat de grenzen aan tijd en grootte staan, werk bij zodra een versie een kwetsbaarheid verhelpt, en laat bij de proxy alleen het adres van uw publicatieketen toe als alleen zij Kroki aanroept.

Hoe gebruik ik mijn Kroki-server met Asciidoctor of MkDocs?

Zet met Asciidoctor het attribuut kroki-server-url op de URL van uw server, en kroki-fetch-diagram om de afbeeldingen tijdens de build te downloaden. Zet met MkDocs server_url in de configuratie van de plugin kroki, en http_method: POST om de afbeeldingen met de site op te slaan.

Waarvan maak ik een back-up op een Kroki-server?

Alleen van zijn configuratie: compose.yaml, een eventueel bestand .env en de configuratie van de reverse proxy. Kroki bewaart geen gegevens, en zijn Docker-images worden opnieuw gedownload met docker compose pull.

Dekt een managed VPS ook Kroki?

Een managed VPS dekt de server: systeem, beveiliging, monitoring en back-ups. Ons team houdt ook uw instantie proactief in de gaten en raadt u de nuttige correcties aan, die u toepast. Een ingreep in de applicatie wordt per uur of tegen een vast bedrag gefactureerd.

Bronnen en officiële documentatie

Neem contact op