Alojar Kroki num VPS gerido: os seus diagramas no seu próprio servidor

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.

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

Todos os guias

O essencial

  1. A licença MIT permite utilizar, modificar e redistribuir livremente o Kroki, numa empresa como em qualquer outro lado, desde que mantenha o seu aviso de direitos de autor.
  2. O Kroki transforma em imagem um diagrama escrito como texto através 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 do seu próprio contentor complementar, ligado ao gateway através das variáveis KROKI_*_HOST: o Docker Compose arranca-os em conjunto.
  4. O Kroki não tem contas nem base de dados. Arranca em modo SECURE, que o impede de ler ficheiros ou a rede; o acesso a uma instância pública controla-se no proxy inverso.
  5. Faça a cópia de segurança 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 faz o Kroki

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.

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

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 gateway e os seus contentores complementares

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.

ImagemO que 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 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.

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

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:

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. Acrescente este serviço, e a variável KROKI_DIAGRAMSNET_HOST=diagramsnet ao bloco environment de kroki:

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

Verificar que tudo responde

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:

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

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 base de dados

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ávelValor predefinidoPara 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 fixam a porta, e KROKI_DIAGRAMSNET_HOST serve 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_LENGTH4096O comprimento de URL aceite 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 adicionalOs 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.

HTTPS: o proxy inverso

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.

Com o Caddy

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:

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

Com o Nginx

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.

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

Proteger uma instância aberta à Internet

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.

Quem chama o seu servidor?

O modo de segurança

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ívelPara que serve
SECURE, por predefiniçãoImpede qualquer tentativa de ler ficheiros do sistema de ficheiros ou recursos da rede
SAFEConfia na limpeza dos pedidos feita pelo modo seguro próprio de cada biblioteca
UNSAFEDesativa todas as funcionalidades de segurança

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

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

Restringir o acesso no proxy

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:

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 ganha a primeira regra que corresponde:

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

Os complementos de terceiros

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.

Ligar o Asciidoctor, o MkDocs e outras ferramentas

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.

Asciidoctor e Antora

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.

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

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

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

As cópias de segurança: a configuração, nenhum dado

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:

ElementoO que guardaCopiar
compose.yamlAs imagens, as suas etiquetas e as variáveis KROKI_*Sim
O ficheiro .env, se existirAs variáveis guardadas fora do compose.yaml, como um token ou um certificadoSim, em lugar seguro
A configuração do proxyO Caddyfile ou o bloco Nginx, e o ficheiro de palavras-passeSim
As imagens DockerO próprio softwareNão: docker compose pull descarrega-as de novo
Terminal, na pasta do compose.yaml
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.

As atualizações

Com etiquetas fixas, mude a versão das quatro imagens no compose.yaml e depois, a partir da sua pasta:

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

Quem faz o quê num VPS gerido

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.

AssuntoAs nossas equipasVocê
O servidorAtualizações do sistema e de segurança, intervenções no servidor incluídasO momento que convém à sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamadaA leitura dos registos da sua instância
KrokiAcompanhamento proativo: erros, lentidão, memória dos complementos e espaço em disco identificados, correção recomendadaA 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 acessoO servidor que os gera, vigiado e com cópias de segurançaO modo de segurança, os complementos, os limites e as regras de acesso do proxy
As cópias de segurançaTodas as noites, cifradas e guardadas fora da máquina; restauro incluídoAs cópias da sua configuração que guarda noutro lugar e o pedido de restauro, quando precisar
A migraçãoO seu servidor atual migrado, oferecidoO 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.

O Kroki, num servidor mantido por si

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.

Descobrir os VPS geridos

Perguntas frequentes

O Kroki é gratuito para uma empresa?

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.

Preciso dos contentores complementares do Kroki?

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.

Como instalar o Kroki com o Docker Compose?

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.

O Kroki tem uma conta de administração?

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.

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

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.

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

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.

O que copiar num servidor Kroki?

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

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.

Fontes e documentação oficial

Contacte-nos