Hospedar Kroki em um VPS gerenciado: seus diagramas em seu próprio servidor

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.

Simon Vasconcelos Lee Por Publicado em 20 de novembro de 2026Leitura: 14 minutos

Todos os guias

O essencial

  1. A licença MIT permite usar, modificar e redistribuir o Kroki livremente, em uma empresa ou fora dela, desde que você mantenha o aviso de copyright dele.
  2. O Kroki transforma em imagem um diagrama escrito como texto por meio de uma única API HTTP: PlantUML, GraphViz, D2, Structurizr e muitos outros vêm na imagem yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw e diagrams.net precisam cada um de seu próprio contêiner complementar, conectado ao gateway pelas variáveis KROKI_*_HOST: o Docker Compose inicia todos juntos.
  4. O Kroki não tem contas nem banco de dados. Ele inicia no modo SECURE, que o impede de ler arquivos ou a rede; o acesso a uma instância pública é controlado no proxy reverso.
  5. Faça backup da configuração, o compose.yaml e a do proxy, e depois atualize com docker compose pull, lendo antes cada nota de versão.

O que o Kroki faz

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.

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 que a licença MIT permite

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 gateway e seus contêineres complementares

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.

ImagemO que ela geraObrigatória
yuzutech/krokiO 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 WireVizSim
yuzutech/kroki-mermaidMermaid: fluxogramas, diagramas de sequência e de GanttNão
yuzutech/kroki-bpmnBPMN, com bpmn-jsNão
yuzutech/kroki-excalidrawExcalidraw, o estilo desenhado à mãoNão
yuzutech/kroki-diagramsnetdiagrams.net, ainda experimentalNão

Dimensionar o servidor

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.

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 instalação com Docker Compose

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:

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

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:

compose.yaml, serviço a adicionar
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Verificar se tudo responde

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:

Terminal, no servidor
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'

Sem Docker: o jar autônomo

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:

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

A configuração: variáveis, sem contas nem banco de dados

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ávelValor padrãoPara que serve
KROKI_SAFE_MODEsecureO nível de segurança, detalhado mais abaixo
KROKI_LISTENTodas as interfaces, porta 8000O 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_HOST127.0.0.1Onde o gateway alcança cada complemento; as variáveis _PORT correspondentes definem a porta, e KROKI_DIAGRAMSNET_HOST atende o diagrams.net
KROKI_COMMAND_TIMEOUT5 segundosA espera máxima por um executável de diagramas, como dot
KROKI_CONVERT_TIMEOUT20 segundosA espera máxima por uma biblioteca Java, como o PlantUML
KROKI_DELEGATE_TIMEOUT_MS30.000A espera máxima por um complemento, em milissegundos
KROKI_MAX_URI_LENGTH4.096O comprimento de URL aceito em GET, acima do qual o Kroki responde 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'O cabeçalho Content-Security-Policy enviado com cada resposta
KROKI_CORS_ALLOWED_HEADERSNenhum extraOs 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.

HTTPS: o proxy reverso

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.

Com o Caddy

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:

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

Com o Nginx

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.

Bloco do 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;
    }
}
Terminal
sudo nginx -t
sudo certbot --nginx

HTTPS sem proxy

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.

Proteger uma instância aberta à internet

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.

Quem chama seu servidor?

O modo de segurança

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ívelPara que serve
SECURE, o padrãoImpede qualquer tentativa de ler arquivos do sistema de arquivos ou recursos da rede
SAFEConfia na limpeza das requisições feita pelo modo seguro próprio de cada biblioteca
UNSAFEDesativa todos os recursos de segurança

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 limites de tamanho e de tempo

Os tempos limite da tabela de configuração delimitam cada conversão. Os complementos acrescentam seus, pensados contra o esgotamento de recursos:

Restringir o acesso no proxy

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:

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

Bloco do Nginx, dentro de location /
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.

Os complementos de terceiros

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.

Conectar o Asciidoctor, o MkDocs e outras ferramentas

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.

Asciidoctor e Antora

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.

Cabeçalho do documento AsciiDoc
:kroki-server-url: https://diagrams.example.com
:kroki-fetch-diagram:

MkDocs

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:

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

Outras integrações

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:

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

Os backups: a configuração, nenhum dado

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:

ElementoO que ele guardaFazer backup
compose.yamlAs imagens, as tags delas e as variáveis KROKI_*Sim
O arquivo .env, se houverAs variáveis mantidas fora do compose.yaml, como um token ou um certificadoSim, em local seguro
A configuração do proxyO Caddyfile ou o bloco do Nginx, e o arquivo de senhasSim
As imagens DockerO próprio softwareNão: docker compose pull baixa todas de novo
Terminal, na pasta do compose.yaml
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.

As atualizações

Com tags fixadas, mude a versão das quatro imagens no compose.yaml e depois, a partir da pasta dele:

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

Quem faz o quê em um VPS gerenciado

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.

AssuntoNossas equipesVocê
O servidorAtualizações do sistema e de segurança, com intervenções no servidor incluídasO momento que convém a sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligaçãoA leitura dos logs de sua instância
KrokiAcompanhamento proativo: erros, lentidões, memória dos complementos e espaço em disco identificados, correção recomendadaA 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 acessoO servidor que os gera, monitorado e com backupO modo de segurança, os complementos, os limites e as regras de acesso do proxy
Os backupsToda noite, criptografados e guardados fora da máquina; restauração incluídaAs cópias de sua configuração que você guarda em outro lugar e o pedido de restauração, quando você precisar
A migraçãoSeu servidor atual migrado, grátisO 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.

Kroki, em um servidor cuidado por nós

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.

Conhecer os VPS gerenciados

Perguntas frequentes

O Kroki é gratuito para uma empresa?

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.

Preciso dos contêineres complementares do Kroki?

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.

Como instalar o Kroki com Docker Compose?

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.

O Kroki tem uma conta de administração?

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.

Como proteger uma instância pública do Kroki?

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.

Como usar meu servidor Kroki com o Asciidoctor ou o MkDocs?

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.

Do que fazer backup em um servidor Kroki?

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

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.

Fontes e documentação oficial

Entre em contato