Ospitare Kroki su un VPS gestito: i vostri diagrammi sul vostro server

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.

Simon Vasconcelos Lee Di Pubblicato il 20 novembre 2026Lettura: 14 minuti

Tutte le guide

In breve

  1. La licenza MIT consente di usare, modificare e ridistribuire Kroki liberamente, in azienda come altrove, a condizione di conservarne l'avviso di copyright.
  2. Kroki trasforma in immagine un diagramma scritto come testo attraverso un'unica API HTTP: PlantUML, GraphViz, D2, Structurizr e molti altri sono inclusi nell'immagine yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw e diagrams.net richiedono ciascuno il proprio container companion, collegato al gateway tramite le variabili KROKI_*_HOST: Docker Compose li avvia insieme.
  4. Kroki non ha account né database. Si avvia in modalità SECURE, che gli impedisce di leggere file o la rete; l'accesso a un'istanza pubblica si controlla sul reverse proxy.
  5. Fate il backup della configurazione, compose.yaml e quella del proxy, poi aggiornate con docker compose pull, leggendo prima ogni nota di rilascio.

Che cosa fa Kroki

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.

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.

Che cosa consente la licenza MIT

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.

Il gateway e i suoi container companion

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.

ImmagineChe cosa generaObbligatoria
yuzutech/krokiIl 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 WireVizSì
yuzutech/kroki-mermaidMermaid: diagrammi di flusso, di sequenza e di GanttNo
yuzutech/kroki-bpmnBPMN, con bpmn-jsNo
yuzutech/kroki-excalidrawExcalidraw, lo stile disegnato a manoNo
yuzutech/kroki-diagramsnetdiagrams.net, ancora sperimentaleNo

Dimensionare il server

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.

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.

L'installazione con Docker Compose

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:

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

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:

compose.yaml, servizio da aggiungere
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Verificare che tutto risponda

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:

Terminale, sul 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'

Senza Docker: il jar autonomo

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:

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

La configurazione: variabili, niente account né database

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:

VariabileValore predefinitoA che cosa serve
KROKI_SAFE_MODEsecureIl livello di sicurezza, descritto più avanti
KROKI_LISTENTutte le interfacce, porta 8000L'indirizzo e la porta di ascolto; accetta anche un socket UNIX, unix:// seguito da un percorso
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Dove il gateway raggiunge ciascun companion; le variabili _PORT corrispondenti fissano la porta, e KROKI_DIAGRAMSNET_HOST serve diagrams.net
KROKI_COMMAND_TIMEOUT5 secondiL'attesa massima per un eseguibile di diagrammi, come dot
KROKI_CONVERT_TIMEOUT20 secondiL'attesa massima per una libreria Java, come PlantUML
KROKI_DELEGATE_TIMEOUT_MS30.000L'attesa massima per un companion, in millisecondi
KROKI_MAX_URI_LENGTH4.096La lunghezza dell'URL accettata in GET, oltre la quale Kroki risponde 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'L'intestazione Content-Security-Policy inviata con ogni risposta
KROKI_CORS_ALLOWED_HEADERSNessuna 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.

HTTPS: il reverse proxy

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.

Con Caddy

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:

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

Con Nginx

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.

Blocco 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;
    }
}
Terminale
sudo nginx -t
sudo certbot --nginx

HTTPS senza proxy

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.

Proteggere un'istanza aperta su Internet

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.

Chi chiama il vostro server?

La modalità di sicurezza

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.

LivelloA che cosa serve
SECURE, predefinitoImpedisce qualsiasi tentativo di leggere file dal file system o risorse dalla rete
SAFESi affida alla pulizia delle richieste svolta dalla modalità sicura propria di ciascuna libreria
UNSAFEDisattiva tutte le funzioni di sicurezza

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 limiti di dimensione e di tempo

I timeout della tabella di configurazione delimitano ogni conversione. I companion aggiungono i propri, pensati contro l'esaurimento delle risorse:

Limitare l'accesso sul proxy

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:

Caddyfile
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:

Blocco Nginx, dentro location /
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.

I companion di terze parti

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.

Collegare Asciidoctor, MkDocs e altri strumenti

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.

Asciidoctor e Antora

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.

Intestazione del documento AsciiDoc
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

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:

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

Altre integrazioni

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:

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

I backup: la configurazione, nessun dato

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:

ElementoChe cosa conservaDa salvare
compose.yamlLe immagini, i loro tag e le variabili KROKI_*Sì
Il file .env, se presenteLe variabili tenute fuori da compose.yaml, come un token o un certificatoSì, in un luogo sicuro
La configurazione del proxyIl Caddyfile o il blocco Nginx, e il file delle passwordSì
Le immagini DockerIl software stessoNo: docker compose pull le scarica di nuovo
Terminale, nella cartella del compose.yaml
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.

Gli aggiornamenti

Con tag fissati, cambiate la versione delle quattro immagini in compose.yaml, poi, dalla sua cartella:

Terminale
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.

Chi fa che cosa su un VPS gestito

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.

ArgomentoI nostri teamVoi
Il serverAggiornamenti del sistema e della sicurezza, interventi sul server compresiIl momento più adatto alla vostra attività
La supervisioneServer seguito 24 ore su 24, 7 giorni su 7, con intervento senza attendere la vostra chiamataLa lettura dei log della vostra istanza
KrokiMonitoraggio proattivo: errori, rallentamenti, memoria dei companion e spazio su disco individuati, correzione raccomandataLa sua installazione, i suoi aggiornamenti e le sue impostazioni, che applicate voi o il vostro assistente IA
I diagrammi e l'accessoIl server che li genera, sorvegliato e salvatoLa modalità di sicurezza, i companion, i limiti e le regole di accesso del proxy
I backupOgni notte, cifrati e conservati fuori dalla macchina; ripristino compresoLe copie della vostra configurazione conservate altrove e la richiesta di ripristino, quando ne avete bisogno
La migrazioneIl vostro server attuale migrato, in omaggioIl 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.

Kroki, su un server gestito per voi

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.

Scoprire i VPS gestiti

Domande frequenti

Kroki è gratuito per un'azienda?

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.

Ho bisogno dei container companion di Kroki?

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.

Come installare Kroki con Docker Compose?

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.

Kroki ha un account di amministrazione?

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.

Come proteggere un'istanza Kroki pubblica?

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.

Come usare il mio server Kroki con Asciidoctor o MkDocs?

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.

Che cosa salvare su un server Kroki?

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 Kroki?

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.

Fonti e documentazione ufficiale

Contattaci