Ospitare Kroki su un VPS gestito significa generare i vostri diagrammi PlantUML, Mermaid, GraphViz, D2, BPMN o Excalidraw su una macchina tutta vostra, che i nostri team tengono aggiornata e supervisionano giorno e notte. Kroki è un software libero con licenza MIT. Questa guida segue la sua documentazione ufficiale: il gateway e i suoi container companion, l'installazione con Docker Compose, la configurazione, HTTPS, la protezione di un'istanza pubblica, il collegamento di Asciidoctor e MkDocs, i backup e gli aggiornamenti.
Di Simon Vasconcelos Lee
Pubblicato il 20 novembre 2026Lettura: 14 minuti
yuzutech/kroki.KROKI_*_HOST: Docker Compose li avvia insieme.SECURE, che gli impedisce di leggere file o la rete; l'accesso a un'istanza pubblica si controlla sul reverse proxy.compose.yaml e quella del proxy, poi aggiornate con docker compose pull, leggendo prima ogni nota di rilascio.Kroki fornisce un'API HTTP unificata che riceve un diagramma descritto come testo e restituisce un'immagine. La vostra documentazione, il vostro wiki o la vostra forge invia il sorgente del diagramma; Kroki risponde con un SVG e, a seconda del tipo di diagramma, un PNG, un PDF o un JPEG. Il suo README elenca BlockDiag, BPMN, Bytefield, C4 con PlantUML, D2, DBML, diagrams.net, Ditaa, Erd, Excalidraw, GoAT, GraphViz, Lini, Mermaid, Nomnoml, Pikchr, PlantUML, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom e WireViz.
/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000. Una pagina web lo mostra allora come qualsiasi altra immagine./graphviz/svg, o nel corpo JSON.Kroki-Diagram-Options-*.La documentazione dell'estensione Asciidoctor Kroki indica tre motivi per far girare un proprio server invece dell'istanza pubblica kroki.io: un firewall aziendale che la blocca, la latenza quando si è lontani da quell'istanza europea e la riservatezza, quando i sorgenti dei diagrammi devono restare all'interno della vostra infrastruttura.
Kroki è pubblicato con la licenza MIT. Questa concede, gratuitamente, il diritto di usare, copiare, modificare, unire, pubblicare, distribuire, concedere in sublicenza e vendere copie del software. Potete quindi farlo girare per la vostra azienda, il vostro team o i vostri clienti, senza alcuna licenza da acquistare.
L'unica condizione è conservare l'avviso di copyright e il testo della licenza in tutte le copie o parti sostanziali del software. Il testo fornisce il software «così com'è», senza garanzia. Le librerie di diagrammi incluse in Kroki conservano ciascuna la propria licenza.
Kroki ha un'architettura modulare. Un gateway scritto in Java, su Vert.x, riceve ogni richiesta e la indirizza alla libreria giusta. Solo l'immagine yuzutech/kroki è obbligatoria: la documentazione osserva che, a seconda dei vostri diagrammi, può bastare.
| Immagine | Che cosa genera | Obbligatoria |
|---|---|---|
yuzutech/kroki | Il gateway, più ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML e C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom e WireViz | Sì |
yuzutech/kroki-mermaid | Mermaid: diagrammi di flusso, di sequenza e di Gantt | No |
yuzutech/kroki-bpmn | BPMN, con bpmn-js | No |
yuzutech/kroki-excalidraw | Excalidraw, lo stile disegnato a mano | No |
yuzutech/kroki-diagramsnet | diagrams.net, ancora sperimentale | No |
La documentazione non fornisce alcuna cifra per la memoria o la CPU. Indica però ciò che pesa di più: i companion Mermaid, BPMN, Excalidraw e diagrams.net generano ogni diagramma in un browser Chromium headless. Perché una raffica di conversioni non superi la memoria del container, ciascuno limita le proprie generazioni simultanee: 6 per impostazione predefinita per Mermaid, BPMN e diagrams.net, 4 per Excalidraw. Le richieste successive attendono il proprio turno in una coda.
yuzutech/kroki 0.36.0 pesa circa 1 GB compressa. Kroki non scrive alcun dato: non conserva nulla tra due richieste.amd64 e arm64.depends_on e KROKI_*_HOST.Su un VPS gestito, descriveteci i vostri diagrammi, i companion di cui hanno bisogno e il traffico che prevedete, e vi consigliamo la taglia giusta.
La documentazione raccomanda i container, Docker o Podman, per non dover installare a mano ogni libreria. Su un server con Docker installato, create una cartella e mettetevi questo compose.yaml, tratto dalla documentazione:
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: è la prima modifica rispetto all'esempio della documentazione, che pubblica 8000:8000. Kroki ascolta per impostazione predefinita su tutte le interfacce, e Docker pubblica una porta su tutti gli indirizzi del server quando non gliene viene indicato nessuno. Qui l'API è raggiungibile solo attraverso il reverse proxy.expose: resta sulla rete interna di Compose, dove il gateway li raggiunge tramite il nome del servizio. Le variabili KROKI_MERMAID_HOST, KROKI_BPMN_HOST e KROKI_EXCALIDRAW_HOST indicano quel nome; le loro porte predefinite, 8002, 8003 e 8004, non vanno ripetute.0.36.0 è la seconda modifica: l'esempio della documentazione segue la versione più recente. Le quattro immagini sono pubblicate insieme con lo stesso tag, il che fissa una versione coerente e rende ogni aggiornamento deliberato.Per diagrams.net, ancora sperimentale, il README aggiunge un quarto companion. Aggiungete questo servizio, e la variabile KROKI_DIAGRAMSNET_HOST=diagramsnet al blocco environment di kroki:
diagramsnet:
image: yuzutech/kroki-diagramsnet:0.36.0
restart: unless-stopped
expose:
- "8005"
Dal server, la rotta /health restituisce lo stato del gateway e le versioni delle librerie che include. Le due richieste successive generano un diagramma GraphViz attraverso il gateway, poi un diagramma Mermaid attraverso il suo companion:
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'
L'altra via della documentazione è il server autonomo, pubblicato nella pagina delle release del repository con il nome kroki-standalone-server-v0.36.0.jar. Richiede Java 21 o successivo, e non include alcuna libreria di diagrammi: ciascuna si installa a parte, e il suo percorso si indica con una variabile come KROKI_DOT_BIN_PATH quando l'eseguibile non è nel PATH. Per l'indirizzo di ascolto, preferite KROKI_LISTEN, perché la documentazione della configurazione annuncia che KROKI_PORT sarà rimosso:
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar
Kroki non ha pagina di amministrazione, né account utente, né database: la sua configurazione è un insieme di variabili d'ambiente, o di proprietà di sistema Java con il jar. In Docker Compose vanno nel blocco environment del servizio interessato, poi docker compose up -d ricrea il container. Le impostazioni che contano di più per un server:
| Variabile | Valore predefinito | A che cosa serve |
|---|---|---|
KROKI_SAFE_MODE | secure | Il livello di sicurezza, descritto più avanti |
KROKI_LISTEN | Tutte le interfacce, porta 8000 | L'indirizzo e la porta di ascolto; accetta anche un socket UNIX, unix:// seguito da un percorso |
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST | 127.0.0.1 | Dove il gateway raggiunge ciascun companion; le variabili _PORT corrispondenti fissano la porta, e KROKI_DIAGRAMSNET_HOST serve diagrams.net |
KROKI_COMMAND_TIMEOUT | 5 secondi | L'attesa massima per un eseguibile di diagrammi, come dot |
KROKI_CONVERT_TIMEOUT | 20 secondi | L'attesa massima per una libreria Java, come PlantUML |
KROKI_DELEGATE_TIMEOUT_MS | 30.000 | L'attesa massima per un companion, in millisecondi |
KROKI_MAX_URI_LENGTH | 4.096 | La lunghezza dell'URL accettata in GET, oltre la quale Kroki risponde 414 |
KROKI_CONTENT_SECURITY_POLICY | script-src 'none'; object-src 'none' | L'intestazione Content-Security-Policy inviata con ogni risposta |
KROKI_CORS_ALLOWED_HEADERS | Nessuna in più | Le intestazioni aggiuntive consentite per le chiamate da un altro sito |
I diagrammi Excalidraw producono URL lunghi. Se aumentate KROKI_MAX_URI_LENGTH, la documentazione raccomanda di restare entro 8.192 caratteri, anche se la maggior parte dei browser ne accetta di più in un tag <img>. Per i diagrammi più grandi, una richiesta POST porta il sorgente nel corpo anziché nell'URL.
Kroki non ha bisogno di alcun segreto per funzionare. Due impostazioni facoltative ne contengono uno: il token KROKI_COMPANION_REGISTRATION_TOKEN, utile se attivate la registrazione di companion di terze parti, trattata nella sezione sulla protezione, e la chiave privata di un certificato, se lasciate che sia Kroki a gestire HTTPS. Teneteli fuori da qualsiasi repository di codice.
Il gateway serve la sua API in HTTP. Un reverse proxy posto davanti ascolta sulle porte 80 e 443, ottiene il certificato Let’s Encrypt, cifra il traffico e lo inoltra a Kroki su 127.0.0.1:8000. È anche il punto in cui si filtra l'accesso, come mostra la sezione successiva.
Caddy ottiene e rinnova da solo il certificato per il nome indicato, e la sua direttiva reverse_proxy trasmette le intestazioni X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host senza alcuna impostazione aggiuntiva:
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
Questo blocco server ascolta sulla porta 80 perché Certbot possa configurare HTTPS. Due limiti di Nginx incontrano quelli di Kroki: un corpo di richiesta oltre 1 MB viene rifiutato per impostazione predefinita con un 413, che client_max_body_size regola per i grandi diagrammi inviati in POST; una riga di richiesta più lunga di 8 KB riceve un 414, che large_client_header_buffers regola se aumentate KROKI_MAX_URI_LENGTH oltre quel valore.
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
La documentazione descrive anche la cifratura da parte di Kroki stesso: KROKI_SSL=true, con il certificato e la chiave privata in formato PEM, come testo tramite KROKI_SSL_CERT e KROKI_SSL_KEY, o come file tramite KROKI_SSL_CERT_PATH e KROKI_SSL_KEY_PATH. Il rinnovo del certificato si fa allora a mano, mentre Caddy o Certbot se ne occupano da soli davanti a un proxy.
Kroki non ha autenticazione: chiunque raggiunga l'API può fargli generare diagrammi. La sua protezione poggia quindi su tre elementi, descritti nella documentazione e nelle note di rilascio: la modalità di sicurezza, i limiti di dimensione e di tempo, e ciò che il proxy lascia passare. Cominciate dallo stabilire chi ha bisogno di raggiungere il vostro server.
kroki-fetch-diagram, il plugin MkDocs con http_method: POST: le immagini vengono salvate con il sito, e il server Kroki non ha più bisogno di essere pubblico.KROKI_SAFE_MODE fissa tre livelli, ciascuno dei quali include le restrizioni del precedente. La documentazione spiega che alcune librerie possono leggere file o URL, come le direttive !include di PlantUML, e che Kroki, che non ne esamina il codice, blocca tali accessi per impostazione predefinita. Invita chiunque gestisca un server a scegliere il livello adatto al proprio uso.
| Livello | A che cosa serve |
|---|---|
SECURE, predefinito | Impedisce qualsiasi tentativo di leggere file dal file system o risorse dalla rete |
SAFE | Si affida alla pulizia delle richieste svolta dalla modalità sicura propria di ciascuna libreria |
UNSAFE | Disattiva tutte le funzioni di sicurezza |
SECURE, i suoi !include e !includeurl vengono rifiutati, e il suo profilo di sicurezza è SANDBOX. In SAFE, il profilo diventa ALLOWLIST, e KROKI_PLANTUML_ALLOWLIST_URL o KROKI_PLANTUML_ALLOWLIST_PATH indicano ciò che può essere incluso.UNSAFE, il loro browser carica solo risorse locali. Per autorizzare una banca di immagini interna senza uscire da questa modalità, la documentazione propone KROKI_ALLOWED_ORIGINS, o la sua forma per singolo companion come KROKI_MERMAID_ALLOWED_ORIGINS, sul container del companion.UNSAFE: niente !include per Structurizr, niente immagini esterne per BlockDiag, niente lettura di file per Lini.KROKI_STRUCTURIZR_SAFE_MODE o KROKI_MERMAID_SAFE_MODE, invece di abbassare il livello dell'intero server.Su un'istanza pubblica, mantenete SECURE. L'intestazione Content-Security-Policy, inviata per impostazione predefinita dalla 0.36.0, completa questa difesa: uno script infilato in un SVG non viene eseguito sull'origine Kroki, nemmeno quando l'immagine viene aperta direttamente.
I timeout della tabella di configurazione delimitano ogni conversione. I companion aggiungono i propri, pensati contro l'esaurimento delle risorse:
KROKI_MERMAID_MAX_TEXT_SIZE) o con più di 500 archi, con un 400, e interrompe una generazione dopo 10 secondi, con un 408. Questi limiti non possono essere superati tramite i parametri di una richiesta.KROKI_MAX_BODY_SIZE).Quando solo la vostra pipeline di pubblicazione chiama Kroki, la soluzione più semplice è accettare soltanto il suo indirizzo IP. Con Caddy, il matcher remote_ip individua gli altri indirizzi, e respond restituisce loro un 403:
diagrams.example.com {
@external not remote_ip 203.0.113.10
respond @external 403
reverse_proxy 127.0.0.1:8000
}
Con Nginx, le direttive allow e deny del blocco location fanno lo stesso lavoro, e vince la prima regola che corrisponde:
allow 203.0.113.10;
deny all;
L'autenticazione di base del proxy è l'altra via: basic_auth con Caddy, la cui password viene sottoposta a hash con caddy hash-password, oppure auth_basic e un file creato con htpasswd con Nginx. È adatta ai client che inviano le credenziali a ogni chiamata, come curl -u; per una pipeline di documentazione, verificate che il suo strumento possa trasmetterle. Per un'istanza che resta pubblica, Nginx può anche limitare il numero di richieste per indirizzo IP con il suo modulo limit_req, calibrato sul numero di diagrammi delle vostre pagine.
Kroki può accogliere companion di terze parti che si registrano tramite l'API /services. Questa scoperta è disattivata per impostazione predefinita, e resta sempre disattivata in modalità SECURE. Se la attivate con KROKI_ENABLE_COMPANION_DISCOVERY=true, la documentazione chiede di tenere /services su una rete fidata, e raccomanda vivamente il token KROKI_COMPANION_REGISTRATION_TOKEN: senza di esso, Kroki avvisa all'avvio che qualsiasi client del gateway può registrare un companion.
Asciidoctor Kroki e il plugin MkDocs puntano per impostazione predefinita a https://kroki.io. Basta indicare loro l'URL del vostro server, prefisso https:// compreso.
L'estensione Asciidoctor Kroki legge l'attributo kroki-server-url, nell'intestazione del documento, sulla riga di comando o nel playbook di Antora. Aggiungete kroki-fetch-diagram per scaricare le immagini al momento della build invece di far puntare l'HTML al vostro server; questa opzione richiede una modalità sicura di Asciidoctor pari a server o inferiore.
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:
Il plugin mkdocs-kroki-plugin legge server_url, che per impostazione predefinita prende la variabile d'ambiente KROKI_SERVER_URL. Con http_method: POST, le immagini vengono salvate accanto a ogni pagina nel sito generato, e messe in cache tra due build:
plugins:
- kroki:
server_url: https://diagrams.example.com
http_method: POST
La pagina degli strumenti di terze parti della documentazione elenca anche GitLab, che genera i diagrammi Kroki in Markdown, AsciiDoc, reST e Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, estensioni per Visual Studio Code e IntelliJ, e Kroki.jl per Julia. Va bene anche qualsiasi client HTTP, come in questo esempio della documentazione:
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'
Kroki è stateless: non conserva nulla tra due richieste, e perfino il registro dei companion di terze parti scompare dopo un riavvio. I sorgenti dei vostri diagrammi vivono nei vostri repository di documentazione, e le loro immagini nei vostri siti generati. Sul server Kroki, ciò che si salva è la sua configurazione:
| Elemento | Che cosa conserva | Da salvare |
|---|---|---|
compose.yaml | Le immagini, i loro tag e le variabili KROKI_* | Sì |
Il file .env, se presente | Le variabili tenute fuori da compose.yaml, come un token o un certificato | Sì, in un luogo sicuro |
| La configurazione del proxy | Il Caddyfile o il blocco Nginx, e il file delle password | Sì |
| Le immagini Docker | Il software stesso | No: docker compose pull le scarica di nuovo |
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile
Adattate la lista al vostro proxy, fate una nuova copia dopo ogni modifica della configurazione e inviatela fuori dal server. Collocata sul suo disco, rientra anche nei suoi backup notturni. Un ripristino consiste nel rimettere al loro posto questi file e lanciare docker compose up -d.
Con tag fissati, cambiate la versione delle quattro immagini in compose.yaml, poi, dalla sua cartella:
docker compose pull
docker compose up -d
Kroki segue il versionamento semantico, e ogni versione pubblica le proprie modifiche in CHANGELOG.md e nella sua pagina di release. Leggetele prima di aggiornare, in particolare la loro sezione «Security»: la 0.35.0 del 5 novembre 2026 e la 0.36.0 del 9 novembre 2026 correggono esecuzioni di codice remoto tramite i diagrammi Bytefield e TikZ, falle XSS in GoAT e DBML, e falsificazioni di richieste lato server tramite BlockDiag e i companion. Su un'istanza aperta, distribuite queste versioni senza attendere.
La versione 0.36.0 aggiunge anche l'intestazione Content-Security-Policy predefinita e il motore di layout TALA per D2. Per l'installazione manuale, documenta Java 21 come versione minima.
Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; Kroki resta il vostro software, con la sua configurazione e i suoi companion.
| Argomento | I nostri team | Voi |
|---|---|---|
| Il server | Aggiornamenti del sistema e della sicurezza, interventi sul server compresi | Il momento più adatto alla vostra attività |
| La supervisione | Server seguito 24 ore su 24, 7 giorni su 7, con intervento senza attendere la vostra chiamata | La lettura dei log della vostra istanza |
| Kroki | Monitoraggio proattivo: errori, rallentamenti, memoria dei companion e spazio su disco individuati, correzione raccomandata | La sua installazione, i suoi aggiornamenti e le sue impostazioni, che applicate voi o il vostro assistente IA |
| I diagrammi e l'accesso | Il server che li genera, sorvegliato e salvato | La modalità di sicurezza, i companion, i limiti e le regole di accesso del proxy |
| I backup | Ogni notte, cifrati e conservati fuori dalla macchina; ripristino compreso | Le copie della vostra configurazione conservate altrove e la richiesta di ripristino, quando ne avete bisogno |
| La migrazione | Il vostro server attuale migrato, in omaggio | Il momento del passaggio |
Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.
Con un VPS gestito Simafri, i nostri team tengono aggiornato il server della vostra istanza Kroki, lo sorvegliano giorno e notte e intervengono senza attendere la vostra chiamata; seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi o il vostro assistente IA. I backup sono cifrati ogni notte e conservati fuori dalla macchina, il loro ripristino è compreso e la migrazione del vostro server attuale è in omaggio.
Sì. Kroki ha licenza MIT: potete usarlo, modificarlo e ridistribuirlo in azienda senza alcuna licenza da acquistare, a condizione di conservarne l'avviso di copyright. Resta il costo del server che lo fa girare.
Solo per i diagrammi che generano. L'immagine yuzutech/kroki basta per PlantUML, GraphViz, D2, Structurizr e la maggior parte dei formati. Mermaid, BPMN, Excalidraw e diagrams.net richiedono ciascuno il proprio companion, collegato tramite KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST o KROKI_DIAGRAMSNET_HOST.
Create un compose.yaml con l'immagine yuzutech/kroki, la sua porta 8000 pubblicata su 127.0.0.1, e i companion che vi servono, come yuzutech/kroki-mermaid, collegati tramite le variabili KROKI_*_HOST. Lanciate docker compose up -d, verificate /health, poi collocate un reverse proxy in HTTPS davanti alla porta 8000.
No, Kroki non ha account, né pagina di amministrazione, né database. La sua configurazione è un insieme di variabili d'ambiente KROKI_*, e l'accesso all'API si controlla sul reverse proxy, per indirizzo IP o con l'autenticazione di base.
Mantenete la modalità SECURE, attiva per impostazione predefinita, che impedisce alle librerie di leggere file o la rete. Lasciate in vigore i limiti di tempo e di dimensione, aggiornate non appena una versione corregge una vulnerabilità e, se solo la vostra pipeline di pubblicazione chiama Kroki, accettate soltanto il suo indirizzo sul proxy.
Con Asciidoctor, indicate l'URL del vostro server nell'attributo kroki-server-url, e kroki-fetch-diagram per scaricare le immagini al momento della build. Con MkDocs, indicate server_url nella configurazione del plugin kroki, e http_method: POST per salvare le immagini con il sito.
Solo la sua configurazione: compose.yaml, l'eventuale file .env e la configurazione del reverse proxy. Kroki non conserva alcun dato, e le sue immagini Docker si scaricano di nuovo con docker compose pull.
Un VPS gestito copre il server: sistema, sicurezza, supervisione e backup. I nostri team seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi. Un intervento nell'applicazione si fattura a ore o a forfait.
Simafri
Parliamo del vostro progetto
Diteci in due parole ciò che vi serve: vi rispondiamo rapidamente.
Grazie! La tua richiesta è stata inviata. Ti risponderemo a breve.
Preferite l'email? Scriveteci a support@simafri.com.