Alojar Kroki num VPS gerido é gerar os seus diagramas PlantUML, Mermaid, GraphViz, D2, BPMN ou Excalidraw numa máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O Kroki é um software livre sob licença MIT. Este guia segue a sua documentação oficial: o gateway e os seus contentores complementares, a instalação com o Docker Compose, a configuração, o HTTPS, a proteção de uma instância pública, a ligação do Asciidoctor e do MkDocs, as cópias de segurança e as atualizações.
Por Simon Vasconcelos Lee
Publicado a 20 de novembro de 2026Leitura: 14 minutos
yuzutech/kroki.KROKI_*_HOST: o Docker Compose arranca-os em conjunto.SECURE, que o impede de ler ficheiros ou a rede; o acesso a uma instância pública controla-se no proxy inverso.compose.yaml e a do proxy, e depois atualize com docker compose pull, lendo antes cada nota de versão.O Kroki oferece uma API HTTP unificada que recebe um diagrama descrito como texto e devolve uma imagem. A sua documentação, a sua wiki ou a sua forja envia o código do diagrama; o Kroki responde com um SVG e, consoante o tipo de diagrama, um PNG, um PDF ou um JPEG. O seu README enumera BlockDiag, BPMN, Bytefield, C4 com 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. Uma página web mostra-o então como qualquer outra imagem./graphviz/svg, ou no corpo JSON.Kroki-Diagram-Options-*.A documentação da extensão Asciidoctor Kroki dá três razões para executar o seu próprio servidor em vez da instância pública kroki.io: uma firewall empresarial que a bloqueia, a latência quando se está longe dessa instância europeia e a confidencialidade, quando o código dos diagramas tem de ficar dentro da sua infraestrutura.
O Kroki é publicado sob a licença MIT. Esta concede, gratuitamente, o direito de utilizar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender cópias do software. Pode, portanto, executá-lo para a sua empresa, a sua equipa ou os seus clientes, sem licença para comprar.
A única condição é manter o aviso de direitos de autor e o texto da licença em todas as cópias ou partes substanciais do software. O texto fornece o software «tal como está», sem garantia. As bibliotecas de diagramas que o Kroki inclui mantêm cada uma a sua própria licença.
O Kroki tem uma arquitetura modular. Um gateway escrito em Java, sobre Vert.x, recebe cada pedido e encaminha-o para a biblioteca certa. Só a imagem yuzutech/kroki é obrigatória: a documentação observa que, consoante os seus diagramas, pode bastar.
| Imagem | O que gera | Obrigatória |
|---|---|---|
yuzutech/kroki | O gateway, mais 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 | Sim |
yuzutech/kroki-mermaid | Mermaid: fluxogramas, diagramas de sequência e de Gantt | Não |
yuzutech/kroki-bpmn | BPMN, com bpmn-js | Não |
yuzutech/kroki-excalidraw | Excalidraw, o estilo desenhado à mão | Não |
yuzutech/kroki-diagramsnet | diagrams.net, ainda experimental | Não |
A documentação não dá nenhum número para a memória ou o processador. Indica, sim, o que mais pesa: os complementos Mermaid, BPMN, Excalidraw e diagrams.net geram cada diagrama num navegador Chromium sem interface. Para que uma rajada de conversões não ultrapasse a memória do contentor, cada um limita as suas gerações simultâneas: 6 por predefinição para Mermaid, BPMN e diagrams.net, 4 para Excalidraw. Os pedidos seguintes aguardam a sua vez numa fila.
yuzutech/kroki 0.36.0 pesa cerca de 1 GB comprimida. O Kroki não escreve nenhum dado: não guarda nada entre dois pedidos.amd64 e arm64.depends_on e KROKI_*_HOST.Num VPS gerido, fale-nos dos seus diagramas, dos complementos de que precisam e do tráfego que prevê, e recomendamos-lhe o tamanho certo.
A documentação recomenda os contentores, Docker ou Podman, para não ter de instalar cada biblioteca à mão. Num servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, retirado da documentação:
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: é a primeira alteração em relação ao exemplo da documentação, que publica 8000:8000. O Kroki escuta por predefinição em todas as interfaces, e o Docker publica uma porta em todos os endereços do servidor quando não lhe é indicado nenhum. Aqui, a API só é acessível através do proxy inverso.expose: ela fica na rede interna do Compose, onde o gateway os alcança pelo nome do serviço. As variáveis KROKI_MERMAID_HOST, KROKI_BPMN_HOST e KROKI_EXCALIDRAW_HOST indicam esse nome; as suas portas predefinidas, 8002, 8003 e 8004, não precisam de ser repetidas.0.36.0 é a segunda alteração: o exemplo da documentação segue a versão mais recente. As quatro imagens são publicadas em conjunto com a mesma etiqueta, o que fixa uma versão coerente e torna cada atualização deliberada.Para o diagrams.net, ainda experimental, o README acrescenta um quarto complemento. Acrescente este serviço, e a variável KROKI_DIAGRAMSNET_HOST=diagramsnet ao bloco environment de kroki:
diagramsnet:
image: yuzutech/kroki-diagramsnet:0.36.0
restart: unless-stopped
expose:
- "8005"
A partir do servidor, a rota /health devolve o estado do gateway e as versões das bibliotecas que inclui. Os dois pedidos seguintes geram um diagrama GraphViz através do gateway e depois um diagrama Mermaid através do seu complemento:
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'
A outra via da documentação é o servidor autónomo, publicado na página de versões do repositório com o nome kroki-standalone-server-v0.36.0.jar. Requer o Java 21 ou posterior, e não inclui nenhuma biblioteca de diagramas: cada uma instala-se à parte, e o seu caminho indica-se com uma variável como KROKI_DOT_BIN_PATH quando o executável não está no PATH. Para o endereço de escuta, prefira KROKI_LISTEN, já que a documentação da configuração anuncia que KROKI_PORT será removida:
KROKI_LISTEN=127.0.0.1:8000 java -jar kroki-standalone-server-v0.36.0.jar
O Kroki não tem página de administração, nem contas de utilizador, nem base de dados: a sua configuração é um conjunto de variáveis de ambiente, ou de propriedades de sistema Java com o jar. No Docker Compose, vão no bloco environment do serviço em causa, e depois docker compose up -d recria o contentor. As definições que mais contam para um servidor:
| Variável | Valor predefinido | Para que serve |
|---|---|---|
KROKI_SAFE_MODE | secure | O nível de segurança, detalhado mais abaixo |
KROKI_LISTEN | Todas as interfaces, porta 8000 | O endereço e a porta de escuta; aceita também um socket UNIX, unix:// seguido de um caminho |
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST | 127.0.0.1 | Onde o gateway alcança cada complemento; as variáveis _PORT correspondentes fixam a porta, e KROKI_DIAGRAMSNET_HOST serve o diagrams.net |
KROKI_COMMAND_TIMEOUT | 5 segundos | A espera máxima por um executável de diagramas, como dot |
KROKI_CONVERT_TIMEOUT | 20 segundos | A espera máxima por uma biblioteca Java, como o PlantUML |
KROKI_DELEGATE_TIMEOUT_MS | 30 000 | A espera máxima por um complemento, em milissegundos |
KROKI_MAX_URI_LENGTH | 4096 | O comprimento de URL aceite em GET, acima do qual o Kroki responde 414 |
KROKI_CONTENT_SECURITY_POLICY | script-src 'none'; object-src 'none' | O cabeçalho Content-Security-Policy enviado com cada resposta |
KROKI_CORS_ALLOWED_HEADERS | Nenhum adicional | Os cabeçalhos adicionais permitidos para as chamadas a partir de outro site |
Os diagramas Excalidraw produzem URL longos. Se aumentar KROKI_MAX_URI_LENGTH, a documentação recomenda ficar pelos 8192 caracteres ou menos, ainda que a maioria dos navegadores aceite mais numa etiqueta <img>. Para os diagramas maiores, um pedido POST leva o código no corpo em vez de no URL.
O Kroki não precisa de nenhum segredo para funcionar. Duas definições opcionais levam um: o token KROKI_COMPANION_REGISTRATION_TOKEN, útil se ativar o registo de complementos de terceiros, abordado na secção sobre a proteção, e a chave privada de um certificado, se deixar o próprio Kroki tratar do HTTPS. Mantenha-os fora de qualquer repositório de código.
O gateway serve a sua API em HTTP. Um proxy inverso colocado à frente escuta nas portas 80 e 443, obtém o certificado Let’s Encrypt, cifra o tráfego e transmite-o ao Kroki em 127.0.0.1:8000. É também aí que se filtra o acesso, como mostra a secção seguinte.
O Caddy obtém e renova sozinho o certificado do nome indicado, e a sua diretiva reverse_proxy transmite os cabeçalhos X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host sem nenhuma definição adicional:
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
Este bloco de site escuta na porta 80 para que o Certbot possa instalar o HTTPS. Dois limites do Nginx cruzam-se com os do Kroki: um corpo de pedido acima de 1 MB é recusado por predefinição com um 413, que client_max_body_size ajusta para os diagramas grandes enviados em POST; uma linha de pedido com mais de 8 KB recebe um 414, que large_client_header_buffers ajusta se aumentar KROKI_MAX_URI_LENGTH para lá desse valor.
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
A documentação descreve também a cifragem pelo próprio Kroki: KROKI_SSL=true, com o certificado e a chave privada em formato PEM, como texto através de KROKI_SSL_CERT e KROKI_SSL_KEY, ou como ficheiros através de KROKI_SSL_CERT_PATH e KROKI_SSL_KEY_PATH. A renovação do certificado faz-se então à mão, ao passo que o Caddy ou o Certbot tratam dela sozinhos à frente de um proxy.
O Kroki não tem autenticação: qualquer pessoa que chegue à API pode pô-lo a gerar diagramas. A sua proteção assenta, portanto, em três elementos, descritos na documentação e nas notas de versão: o modo de segurança, os limites de tamanho e de tempo, e o que o proxy deixa passar. Comece por determinar quem precisa de chegar ao seu servidor.
kroki-fetch-diagram, o plugin MkDocs com http_method: POST: as imagens são guardadas com o site, e o servidor Kroki deixa de precisar de ser público.KROKI_SAFE_MODE fixa três níveis, cada um dos quais inclui as restrições do anterior. A documentação explica que algumas bibliotecas podem ler ficheiros ou URL, como as diretivas !include do PlantUML, e que o Kroki, que não revê o código delas, bloqueia esses acessos por predefinição. Convida quem gere um servidor a escolher o nível que convém ao seu uso.
| Nível | Para que serve |
|---|---|
SECURE, por predefinição | Impede qualquer tentativa de ler ficheiros do sistema de ficheiros ou recursos da rede |
SAFE | Confia na limpeza dos pedidos feita pelo modo seguro próprio de cada biblioteca |
UNSAFE | Desativa todas as funcionalidades de segurança |
SECURE, os seus !include e !includeurl são recusados, e o seu perfil de segurança é SANDBOX. Em SAFE, o perfil passa a ALLOWLIST, e KROKI_PLANTUML_ALLOWLIST_URL ou KROKI_PLANTUML_ALLOWLIST_PATH indicam o que pode ser incluído.UNSAFE, o seu navegador só carrega recursos locais. Para autorizar um banco de imagens interno sem sair desse modo, a documentação propõe KROKI_ALLOWED_ORIGINS, ou a sua forma por complemento como KROKI_MERMAID_ALLOWED_ORIGINS, no contentor do complemento.UNSAFE: sem !include para o Structurizr, sem imagem externa para o BlockDiag, sem leitura de ficheiros para o Lini.KROKI_STRUCTURIZR_SAFE_MODE ou KROKI_MERMAID_SAFE_MODE, em vez de baixar o nível do servidor inteiro.Numa instância pública, mantenha SECURE. O cabeçalho Content-Security-Policy, enviado por predefinição desde a 0.36.0, completa esta defesa: um script introduzido num SVG não é executado na origem do Kroki, mesmo quando a imagem é aberta diretamente.
Os tempos limite da tabela de configuração delimitam cada conversão. Os complementos acrescentam os seus, pensados contra o esgotamento de recursos:
KROKI_MERMAID_MAX_TEXT_SIZE) ou com mais de 500 arestas, com um 400, e interrompe uma geração ao fim de 10 segundos, com um 408. Estes limites não podem ser alterados através dos parâmetros de um pedido.KROKI_MAX_BODY_SIZE).Quando só a sua cadeia de publicação chama o Kroki, o mais simples é aceitar apenas o seu endereço IP. Com o Caddy, o comparador remote_ip seleciona os outros endereços, e respond devolve-lhes um 403:
diagrams.example.com {
@external not remote_ip 203.0.113.10
respond @external 403
reverse_proxy 127.0.0.1:8000
}
Com o Nginx, as diretivas allow e deny do bloco location fazem o mesmo trabalho, e ganha a primeira regra que corresponde:
allow 203.0.113.10;
deny all;
A autenticação básica do proxy é a outra via: basic_auth com o Caddy, cuja palavra-passe é cifrada com caddy hash-password, ou auth_basic e um ficheiro criado com htpasswd com o Nginx. Convém aos clientes que enviam as credenciais em cada chamada, como curl -u; para uma cadeia de documentação, verifique se a sua ferramenta as consegue transmitir. Para uma instância que continua pública, o Nginx pode ainda limitar o número de pedidos por endereço IP com o seu módulo limit_req, ajustado ao número de diagramas das suas páginas.
O Kroki pode acolher complementos de terceiros que se registam através da API /services. Esta descoberta está desativada por predefinição, e fica sempre desativada em modo SECURE. Se a ativar com KROKI_ENABLE_COMPANION_DISCOVERY=true, a documentação pede que mantenha /services numa rede de confiança, e recomenda vivamente o token KROKI_COMPANION_REGISTRATION_TOKEN: sem ele, o Kroki avisa no arranque que qualquer cliente do gateway pode registar um complemento.
O Asciidoctor Kroki e o plugin MkDocs apontam por predefinição para https://kroki.io. Basta-lhes o URL do seu servidor, com o prefixo https:// incluído.
A extensão Asciidoctor Kroki lê o atributo kroki-server-url, no cabeçalho do documento, na linha de comandos ou no playbook do Antora. Acrescente kroki-fetch-diagram para descarregar as imagens no momento da compilação em vez de o HTML apontar para o seu servidor; esta opção requer um modo seguro do Asciidoctor igual a server ou inferior.
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:
O plugin mkdocs-kroki-plugin lê server_url, que por predefinição assume a variável de ambiente KROKI_SERVER_URL. Com http_method: POST, as imagens são guardadas junto de cada página no site compilado, e mantidas em cache entre duas compilações:
plugins:
- kroki:
server_url: https://diagrams.example.com
http_method: POST
A página de ferramentas de terceiros da documentação enumera também o GitLab, que gera os diagramas Kroki em Markdown, AsciiDoc, reST e Textile, o Sphinx, o Jekyll, o Hugo, o Remark, o Python-Markdown, o MediaWiki, extensões para o Visual Studio Code e o IntelliJ, e o Kroki.jl para Julia. Qualquer cliente HTTP também serve, como neste exemplo da documentação:
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'
O Kroki não tem estado: não guarda nada entre dois pedidos, e até o registo dos complementos de terceiros desaparece após um reinício. O código dos seus diagramas vive nos seus repositórios de documentação, e as imagens nos seus sites compilados. No servidor Kroki, o que se copia é a sua configuração:
| Elemento | O que guarda | Copiar |
|---|---|---|
compose.yaml | As imagens, as suas etiquetas e as variáveis KROKI_* | Sim |
O ficheiro .env, se existir | As variáveis guardadas fora do compose.yaml, como um token ou um certificado | Sim, em lugar seguro |
| A configuração do proxy | O Caddyfile ou o bloco Nginx, e o ficheiro de palavras-passe | Sim |
| As imagens Docker | O próprio software | Não: docker compose pull descarrega-as de novo |
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile
Adapte a lista ao seu proxy, faça uma nova cópia após cada alteração de configuração e envie-a para fora do servidor. Guardada no seu disco, entra também nas suas cópias de segurança noturnas. Um restauro consiste em repor estes ficheiros e executar docker compose up -d.
Com etiquetas fixas, mude a versão das quatro imagens no compose.yaml e depois, a partir da sua pasta:
docker compose pull
docker compose up -d
O Kroki segue o versionamento semântico, e cada versão publica as suas alterações no CHANGELOG.md e na sua página de versão. Leia-as antes de atualizar, sobretudo a secção «Security»: a 0.35.0 de 5 de novembro de 2026 e a 0.36.0 de 9 de novembro de 2026 corrigem execuções remotas de código através dos diagramas Bytefield e TikZ, falhas XSS no GoAT e no DBML, e falsificações de pedidos do lado do servidor através do BlockDiag e dos complementos. Numa instância aberta, implemente estas versões sem esperar.
A versão 0.36.0 acrescenta também o cabeçalho Content-Security-Policy por predefinição e o motor de disposição TALA para o D2. Para a instalação manual, documenta o Java 21 como versão mínima.
O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Kroki continua a ser o seu software, com a sua configuração e os seus complementos.
| Assunto | As nossas equipas | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, intervenções no servidor incluídas | O momento que convém à sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamada | A leitura dos registos da sua instância |
| Kroki | Acompanhamento proativo: erros, lentidão, memória dos complementos e espaço em disco identificados, correção recomendada | A sua instalação, as suas atualizações e as suas definições, que aplica diretamente ou com o seu assistente de IA |
| Os diagramas e o acesso | O servidor que os gera, vigiado e com cópias de segurança | O modo de segurança, os complementos, os limites e as regras de acesso do proxy |
| As cópias de segurança | Todas as noites, cifradas e guardadas fora da máquina; restauro incluído | As cópias da sua configuração que guarda noutro lugar e o pedido de restauro, quando precisar |
| A migração | O seu servidor atual migrado, oferecido | O momento da mudança |
Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.
Com um VPS gerido da Simafri, as nossas equipas mantêm atualizado o servidor da sua instância Kroki, vigiam-no dia e noite e intervêm sem esperar pela sua chamada; acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica diretamente ou com o seu assistente de IA. As cópias de segurança são cifradas todas as noites e guardadas fora da máquina, o seu restauro está incluído, e a migração do seu servidor atual é oferecida.
Sim. O Kroki está sob licença MIT: pode utilizá-lo, modificá-lo e redistribuí-lo numa empresa sem licença para comprar, desde que mantenha o seu aviso de direitos de autor. Resta o custo do servidor que o faz funcionar.
Apenas para os diagramas que geram. A imagem yuzutech/kroki basta para PlantUML, GraphViz, D2, Structurizr e a maioria dos formatos. Mermaid, BPMN, Excalidraw e diagrams.net precisam cada um do seu complemento, ligado através de KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST ou KROKI_DIAGRAMSNET_HOST.
Crie um compose.yaml com a imagem yuzutech/kroki, a sua porta 8000 publicada em 127.0.0.1, e os complementos de que precisa, como yuzutech/kroki-mermaid, ligados através das variáveis KROKI_*_HOST. Execute docker compose up -d, verifique /health e coloque depois um proxy inverso em HTTPS à frente da porta 8000.
Não, o Kroki não tem contas, nem página de administração, nem base de dados. A sua configuração é um conjunto de variáveis de ambiente KROKI_*, e o acesso à API controla-se no proxy inverso, por endereço IP ou com autenticação básica.
Mantenha o modo SECURE, ativo por predefinição, que impede as bibliotecas de ler ficheiros ou a rede. Mantenha os limites de tempo e de tamanho, atualize assim que uma versão corrigir uma vulnerabilidade e, se só a sua cadeia de publicação chamar o Kroki, aceite apenas o seu endereço no proxy.
Com o Asciidoctor, indique o URL do seu servidor no atributo kroki-server-url, e kroki-fetch-diagram para descarregar as imagens no momento da compilação. Com o MkDocs, indique server_url na configuração do plugin kroki, e http_method: POST para guardar as imagens com o site.
Apenas a sua configuração: o compose.yaml, o eventual ficheiro .env e a configuração do proxy inverso. O Kroki não guarda nenhum dado, e as suas imagens Docker voltam a ser descarregadas com docker compose pull.
Um VPS gerido cobre o servidor: sistema, segurança, supervisão e cópias de segurança. As nossas equipas acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica. Uma intervenção na aplicação é faturada à hora ou por pacote.
Simafri
Vamos falar do seu projeto
Diga-nos em poucas palavras o que precisa: respondemos-lhe rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o email? Escreva-nos para support@simafri.com.