Hospedar o Kroki em um VPS gerenciado é gerar seus diagramas PlantUML, Mermaid, GraphViz, D2, BPMN ou Excalidraw em uma máquina própria, que nossas equipes mantêm atualizada e supervisionam dia e noite. O Kroki é um software livre sob a licença MIT. Este guia segue a documentação oficial dele: o gateway e seus contêineres complementares, a instalação com Docker Compose, a configuração, o HTTPS, a proteção de uma instância pública, a conexão do Asciidoctor e do MkDocs, os backups e as atualizações.
Por Simon Vasconcelos Lee
Publicado em 20 de novembro de 2026Leitura: 14 minutos
yuzutech/kroki.KROKI_*_HOST: o Docker Compose inicia todos juntos.SECURE, que o impede de ler arquivos ou a rede; o acesso a uma instância pública é controlado no proxy reverso.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. Sua documentação, sua wiki ou sua forja envia o código do diagrama; o Kroki responde com um SVG e, conforme o tipo de diagrama, um PNG, um PDF ou um JPEG. O README dele lista 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 então o exibe como qualquer outra imagem./graphviz/svg, ou no corpo JSON.Kroki-Diagram-Options-*.A documentação da extensão Asciidoctor Kroki dá três motivos para rodar seu próprio servidor em vez da instância pública kroki.io: um firewall corporativo que a bloqueia, a latência quando se está longe dessa instância europeia e a privacidade, quando o código dos diagramas precisa ficar dentro de sua infraestrutura.
O Kroki é publicado sob a licença MIT. Ela concede, gratuitamente, o direito de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e vender cópias do software. Você pode, portanto, rodá-lo para sua empresa, sua equipe ou seus clientes, sem licença a comprar.
A única condição é manter o aviso de copyright e o texto da licença em todas as cópias ou partes substanciais do software. O texto fornece o software “no estado em que se encontra”, sem garantia. As bibliotecas de diagramas que o Kroki inclui mantêm cada uma a própria licença.
O Kroki tem uma arquitetura modular. Um gateway escrito em Java, sobre o Vert.x, recebe cada requisição e a encaminha para a biblioteca certa. Só a imagem yuzutech/kroki é obrigatória: a documentação observa que, dependendo de seus diagramas, ela pode bastar.
| Imagem | O que ela 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 memória ou CPU. Ela diz, sim, o que mais pesa: os complementos Mermaid, BPMN, Excalidraw e diagrams.net geram cada diagrama em um navegador Chromium headless. Para que uma rajada de conversões não ultrapasse a memória do contêiner, cada um limita suas gerações simultâneas: 6 por padrão para Mermaid, BPMN e diagrams.net, 4 para Excalidraw. As requisições seguintes esperam a vez em uma fila.
yuzutech/kroki 0.36.0 tem cerca de 1 GB compactada. O Kroki não grava nenhum dado: ele não guarda nada entre duas requisições.amd64 e arm64.depends_on e KROKI_*_HOST deles.Em um VPS gerenciado, conte para nós sobre seus diagramas, os complementos de que eles precisam e o tráfego que você espera, e recomendamos o tamanho certo.
A documentação recomenda os contêineres, Docker ou Podman, para que você não precise instalar cada biblioteca à mão. Em um servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, tirado 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 mudança em relação ao exemplo da documentação, que publica 8000:8000. O Kroki escuta por padrão em todas as interfaces, e o Docker publica uma porta em todos os endereços do servidor quando nenhum é informado. Aqui, a API só é acessível pelo proxy reverso.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 informam esse nome; as portas padrão deles, 8002, 8003 e 8004, não precisam ser repetidas.0.36.0 é a segunda mudança: o exemplo da documentação segue a versão mais recente. As quatro imagens são publicadas juntas com a mesma tag, 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. Adicione 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 retorna o status do gateway e as versões das bibliotecas que ele inclui. As duas requisições seguintes geram um diagrama GraphViz pelo gateway e depois um diagrama Mermaid pelo complemento dele:
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 releases do repositório com o nome kroki-standalone-server-v0.36.0.jar. Ele exige o Java 21 ou posterior, e não inclui nenhuma biblioteca de diagramas: cada uma é instalada à parte, e o caminho dela é informado 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 de 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 usuário, nem banco de dados: a configuração dele é um conjunto de variáveis de ambiente, ou de propriedades de sistema Java com o jar. No Docker Compose, elas vão no bloco environment do serviço em questão, e depois docker compose up -d recria o contêiner. As configurações que mais contam para um servidor:
| Variável | Valor padrão | 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 definem a porta, e KROKI_DIAGRAMSNET_HOST atende 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 | 4.096 | O comprimento de URL aceito 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 extra | Os cabeçalhos adicionais permitidos para chamadas vindas de outro site |
Os diagramas Excalidraw produzem URLs longas. Se você aumentar KROKI_MAX_URI_LENGTH, a documentação recomenda ficar em 8.192 caracteres ou menos, mesmo que a maioria dos navegadores aceite mais em uma tag <img>. Para os diagramas maiores, uma requisição POST leva o código no corpo em vez de na URL.
O Kroki não precisa de nenhum segredo para funcionar. Duas configurações opcionais carregam um: o token KROKI_COMPANION_REGISTRATION_TOKEN, útil se você ativar o registro de complementos de terceiros, tratado na seção sobre proteção, e a chave privada de um certificado, se você deixar o próprio Kroki cuidar do HTTPS. Mantenha-os fora de qualquer repositório de código.
O gateway serve a API dele em HTTP. Um proxy reverso colocado na frente escuta nas portas 80 e 443, obtém o certificado Let’s Encrypt, criptografa o tráfego e o repassa ao Kroki em 127.0.0.1:8000. É também nele que o acesso é filtrado, como mostra a seção seguinte.
O Caddy obtém e renova sozinho o certificado do nome informado, e a diretiva reverse_proxy dele repassa os cabeçalhos X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host sem nenhuma configuração extra:
diagrams.example.com {
encode gzip
reverse_proxy 127.0.0.1:8000
}
Este bloco de servidor escuta na porta 80 para que o Certbot possa configurar o HTTPS. Dois limites do Nginx encontram os do Kroki: um corpo de requisição acima de 1 MB é recusado por padrão com um 413, que client_max_body_size ajusta para diagramas grandes enviados em POST; uma linha de requisição com mais de 8 KB recebe um 414, que large_client_header_buffers ajusta se você aumentar KROKI_MAX_URI_LENGTH além disso.
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 criptografia pelo próprio Kroki: KROKI_SSL=true, com o certificado e a chave privada em formato PEM, como texto por KROKI_SSL_CERT e KROKI_SSL_KEY, ou como arquivos por KROKI_SSL_CERT_PATH e KROKI_SSL_KEY_PATH. A renovação do certificado passa então a ser feita à mão, enquanto o Caddy ou o Certbot cuidam dela sozinhos na frente de um proxy.
O Kroki não tem autenticação: qualquer pessoa que chegue à API pode fazê-lo gerar diagramas. A proteção dele se apoia, 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 definindo quem precisa chegar a seu servidor.
kroki-fetch-diagram, o plugin do MkDocs com http_method: POST: as imagens são salvas com o site, e o servidor Kroki não precisa mais ser público.KROKI_SAFE_MODE define três níveis, cada um incluindo as restrições do anterior. A documentação explica que algumas bibliotecas podem ler arquivos ou URLs, como as diretivas !include do PlantUML, e que o Kroki, que não revisa o código delas, bloqueia esses acessos por padrão. Ela convida quem roda um servidor a escolher o nível adequado a seu uso.
| Nível | Para que serve |
|---|---|
SECURE, o padrão | Impede qualquer tentativa de ler arquivos do sistema de arquivos ou recursos da rede |
SAFE | Confia na limpeza das requisições feita pelo modo seguro próprio de cada biblioteca |
UNSAFE | Desativa todos os recursos de segurança |
SECURE, os !include e !includeurl dele são recusados, e o 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 navegador deles só carrega recursos locais. Para autorizar um banco de imagens interno sem sair desse modo, a documentação oferece KROKI_ALLOWED_ORIGINS, ou a forma por complemento, como KROKI_MERMAID_ALLOWED_ORIGINS, no contêiner do complemento.UNSAFE: sem !include para o Structurizr, sem imagem externa para o BlockDiag, sem leitura de arquivos para o Lini.KROKI_STRUCTURIZR_SAFE_MODE ou KROKI_MERMAID_SAFE_MODE, em vez de baixar o nível do servidor inteiro.Em uma instância pública, mantenha SECURE. O cabeçalho Content-Security-Policy, enviado por padrão desde a 0.36.0, completa essa defesa: um script inserido em um 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 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 após 10 segundos, com um 408. Esses limites não podem ser alterados pelos parâmetros de uma requisição.KROKI_MAX_BODY_SIZE).Quando apenas seu pipeline de publicação chama o Kroki, o mais simples é aceitar somente o endereço IP dele. Com o Caddy, o matcher remote_ip seleciona os outros endereços, e respond devolve a eles 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 vale a primeira regra que corresponder:
allow 203.0.113.10;
deny all;
A autenticação básica do proxy é a outra via: basic_auth com o Caddy, cuja senha passa por hash com caddy hash-password, ou auth_basic e um arquivo criado com htpasswd com o Nginx. Ela serve para clientes que enviam as credenciais a cada chamada, como curl -u; para um pipeline de documentação, verifique se a ferramenta dele consegue repassá-las. Para uma instância que continua pública, o Nginx também pode limitar o número de requisições por endereço IP com o módulo limit_req, ajustado ao número de diagramas de suas páginas.
O Kroki pode receber complementos de terceiros que se registram pela API /services. Essa descoberta vem desativada por padrão, e fica sempre desligada no modo SECURE. Se você a ativar com KROKI_ENABLE_COMPANION_DISCOVERY=true, a documentação pede para manter /services em uma rede confiável, e recomenda fortemente o token KROKI_COMPANION_REGISTRATION_TOKEN: sem ele, o Kroki avisa na inicialização que qualquer cliente do gateway pode registrar um complemento.
O Asciidoctor Kroki e o plugin do MkDocs apontam por padrão para https://kroki.io. Basta informar a eles a URL de 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 comando ou no playbook do Antora. Adicione kroki-fetch-diagram para baixar as imagens no build em vez de fazer o HTML apontar para seu servidor; essa opção exige 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 padrão assume a variável de ambiente KROKI_SERVER_URL. Com http_method: POST, as imagens são armazenadas ao lado de cada página no site gerado, e ficam em cache entre dois builds:
plugins:
- kroki:
server_url: https://diagrams.example.com
http_method: POST
A página de ferramentas de terceiros da documentação lista 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 funciona, como neste exemplo da documentação:
curl https://diagrams.example.com/erd/svg --data-binary '@project.erd'
O Kroki não tem estado: ele não guarda nada entre duas requisições, e até o registro dos complementos de terceiros some após uma reinicialização. O código de seus diagramas fica em seus repositórios de documentação, e as imagens deles em seus sites gerados. No servidor Kroki, o que entra no backup é a configuração dele:
| Elemento | O que ele guarda | Fazer backup |
|---|---|---|
compose.yaml | As imagens, as tags delas e as variáveis KROKI_* | Sim |
O arquivo .env, se houver | As variáveis mantidas fora do compose.yaml, como um token ou um certificado | Sim, em local seguro |
| A configuração do proxy | O Caddyfile ou o bloco do Nginx, e o arquivo de senhas | Sim |
| As imagens Docker | O próprio software | Não: docker compose pull baixa todas de novo |
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile
Adapte a lista a seu proxy, faça uma nova cópia após cada mudança de configuração e envie-a para fora do servidor. Guardada no disco dele, ela também entra nos backups noturnos. Uma restauração consiste em recolocar esses arquivos no lugar e executar docker compose up -d.
Com tags fixadas, mude a versão das quatro imagens no compose.yaml e depois, a partir da pasta dele:
docker compose pull
docker compose up -d
O Kroki segue o versionamento semântico, e cada versão publica as mudanças dela no CHANGELOG.md e na página de release. Leia-as antes de atualizar, principalmente a seçã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 por meio dos diagramas Bytefield e TikZ, falhas XSS no GoAT e no DBML, e falsificações de requisição do lado do servidor por meio do BlockDiag e dos complementos. Em uma instância aberta, implante essas versões sem esperar.
A versão 0.36.0 também acrescenta o cabeçalho Content-Security-Policy padrão e o motor de layout TALA para o D2. Para a instalação manual, ela documenta o Java 21 como versão mínima.
A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Kroki continua sendo seu software, com a configuração e os complementos dele.
| Assunto | Nossas equipes | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, com intervenções no servidor incluídas | O momento que convém a sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligação | A leitura dos logs de sua instância |
| Kroki | Acompanhamento proativo: erros, lentidões, memória dos complementos e espaço em disco identificados, correção recomendada | A instalação, as atualizações e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA |
| Os diagramas e o acesso | O servidor que os gera, monitorado e com backup | O modo de segurança, os complementos, os limites e as regras de acesso do proxy |
| Os backups | Toda noite, criptografados e guardados fora da máquina; restauração incluída | As cópias de sua configuração que você guarda em outro lugar e o pedido de restauração, quando você precisar |
| A migração | Seu servidor atual migrado, grátis | O momento da virada |
Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.
Com um VPS gerenciado Simafri, nossas equipes mantêm atualizado o servidor de sua instância Kroki, monitoram-no dia e noite e intervêm sem esperar sua ligação; elas também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica por conta própria ou com seu assistente de IA. Os backups são criptografados todas as noites e guardados fora da máquina, a restauração está incluída, e a migração de seu servidor atual é grátis.
Sim. O Kroki está sob a licença MIT: você pode usá-lo, modificá-lo e redistribuí-lo em uma empresa sem licença a comprar, desde que mantenha o aviso de copyright dele. Resta o custo do servidor em que ele roda.
Só para os diagramas que eles 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 de seu complemento, conectado por KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST ou KROKI_DIAGRAMSNET_HOST.
Crie um compose.yaml com a imagem yuzutech/kroki, a porta 8000 dela publicada em 127.0.0.1, e os complementos de que você precisa, como yuzutech/kroki-mermaid, conectados pelas variáveis KROKI_*_HOST. Execute docker compose up -d, verifique /health e coloque então um proxy reverso em HTTPS na frente da porta 8000.
Não, o Kroki não tem contas, nem página de administração, nem banco de dados. A configuração dele é um conjunto de variáveis de ambiente KROKI_*, e o acesso à API é controlado no proxy reverso, por endereço IP ou com autenticação básica.
Mantenha o modo SECURE, ativo por padrão, que impede as bibliotecas de ler arquivos ou a rede. Mantenha os limites de tempo e de tamanho, atualize assim que uma versão corrigir uma vulnerabilidade e, se só seu pipeline de publicação chamar o Kroki, aceite apenas o endereço dele no proxy.
Com o Asciidoctor, informe a URL de seu servidor no atributo kroki-server-url, e kroki-fetch-diagram para baixar as imagens no build. Com o MkDocs, informe server_url na configuração do plugin kroki, e http_method: POST para armazenar as imagens com o site.
Só da configuração dele: o compose.yaml, o arquivo .env, se houver, e a configuração do proxy reverso. O Kroki não guarda nenhum dado, e as imagens Docker dele são baixadas de novo com docker compose pull.
Um VPS gerenciado cobre o servidor: sistema, segurança, supervisão e backups. Nossas equipes também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica. Uma intervenção na aplicação é cobrada por hora ou por valor fechado.
Simafri
Vamos falar de seu site
Conte para a gente sobre seu projeto em poucas palavras: responderemos rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o e-mail? Escreva para a gente em support@simafri.com.