Alojar Kroki en un VPS administrado: sus diagramas, en su propio servidor

Alojar Kroki en un VPS administrado significa generar sus diagramas PlantUML, Mermaid, GraphViz, D2, BPMN o Excalidraw en una máquina propia, que nuestros equipos mantienen actualizada y supervisan día y noche. Kroki es software libre con licencia MIT. Esta guía sigue su documentación oficial: la pasarela y sus contenedores complementarios, la instalación con Docker Compose, la configuración, HTTPS, la protección de una instancia pública, la conexión de Asciidoctor y MkDocs, las copias de seguridad y las actualizaciones.

Simon Vasconcelos Lee Por Publicado el 20 de noviembre de 202614 minutos de lectura

Todas las guías

Lo esencial

  1. La licencia MIT permite usar, modificar y redistribuir Kroki libremente, en una empresa o en cualquier otro ámbito, siempre que conserve su aviso de copyright.
  2. Kroki convierte en imagen un diagrama escrito como texto mediante una única API HTTP: PlantUML, GraphViz, D2, Structurizr y muchos más vienen en la imagen yuzutech/kroki.
  3. Mermaid, BPMN, Excalidraw y diagrams.net necesitan cada uno su propio contenedor complementario, conectado a la pasarela mediante las variables KROKI_*_HOST: Docker Compose los arranca juntos.
  4. Kroki no tiene cuentas ni base de datos. Arranca en modo SECURE, que le impide leer archivos o la red; el acceso a una instancia pública se controla en el proxy inverso.
  5. Haga copia de la configuración, compose.yaml y la del proxy, y actualice después con docker compose pull, leyendo antes cada nota de versión.

Qué hace Kroki

Kroki ofrece una API HTTP unificada que recibe un diagrama descrito como texto y devuelve una imagen. Su documentación, su wiki o su forja envía el código del diagrama; Kroki responde con un SVG y, según el tipo de diagrama, un PNG, un PDF o un JPEG. Su README enumera 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 y WireViz.

La documentación de la extensión Asciidoctor Kroki da tres razones para ejecutar su propio servidor en lugar de la instancia pública kroki.io: un cortafuegos de empresa que la bloquea, la latencia cuando se está lejos de esa instancia europea y la confidencialidad, cuando el código de los diagramas debe quedarse dentro de su infraestructura.

Lo que permite la licencia MIT

Kroki se publica bajo la licencia MIT. Concede, de forma gratuita, el derecho a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y vender copias del software. Puede, por tanto, ejecutarlo para su empresa, su equipo o sus clientes, sin ninguna licencia que comprar.

La única condición es conservar el aviso de copyright y el texto de la licencia en todas las copias o partes sustanciales del software. El texto ofrece el software «tal cual», sin garantía. Las bibliotecas de diagramas que Kroki incluye conservan cada una su propia licencia.

La pasarela y sus contenedores complementarios

Kroki tiene una arquitectura modular. Una pasarela escrita en Java, sobre Vert.x, recibe cada petición y la dirige a la biblioteca adecuada. Solo la imagen yuzutech/kroki es obligatoria: la documentación señala que, según sus diagramas, puede bastar.

ImagenLo que generaObligatoria
yuzutech/krokiLa pasarela, además de ActDiag, BlockDiag, Bytefield, D2, Ditaa, Erd, GoAT, GraphViz, Lini, Nomnoml, NwDiag, PacketDiag, Pikchr, PlantUML y C4, RackDiag, SeqDiag, Structurizr, Svgbob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom y WireVizSí
yuzutech/kroki-mermaidMermaid: diagramas de flujo, de secuencia y de GanttNo
yuzutech/kroki-bpmnBPMN, con bpmn-jsNo
yuzutech/kroki-excalidrawExcalidraw, el estilo dibujado a manoNo
yuzutech/kroki-diagramsnetdiagrams.net, todavía experimentalNo

Dimensionar el servidor

La documentación no da ninguna cifra de memoria ni de procesador. Sí indica lo que más pesa: los complementos Mermaid, BPMN, Excalidraw y diagrams.net generan cada diagrama en un navegador Chromium sin interfaz. Para que una ráfaga de conversiones no supere la memoria del contenedor, cada uno limita sus generaciones simultáneas: 6 por defecto para Mermaid, BPMN y diagrams.net, 4 para Excalidraw. Las peticiones siguientes esperan su turno en una cola.

En un VPS administrado, cuéntenos cómo son sus diagramas, los complementos que necesitan y el tráfico que espera, y le recomendamos el tamaño adecuado.

La instalación con Docker Compose

La documentación recomienda los contenedores, Docker o Podman, para no tener que instalar cada biblioteca a mano. En un servidor con Docker instalado, cree una carpeta y coloque en ella este compose.yaml, tomado de la documentación:

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 diagrams.net, todavía experimental, el README añade un cuarto complemento. Añada este servicio, y la variable KROKI_DIAGRAMSNET_HOST=diagramsnet al bloque environment de kroki:

compose.yaml, servicio que añadir
  diagramsnet:
    image: yuzutech/kroki-diagramsnet:0.36.0
    restart: unless-stopped
    expose:
      - "8005"

Comprobar que todo responde

Desde el servidor, la ruta /health devuelve el estado de la pasarela y las versiones de las bibliotecas que incluye. Las dos peticiones siguientes generan un diagrama GraphViz a través de la pasarela y después un diagrama Mermaid a través de su complemento:

Terminal, en el 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'

Sin Docker: el jar autónomo

La otra vía de la documentación es el servidor autónomo, publicado en la página de versiones del repositorio con el nombre kroki-standalone-server-v0.36.0.jar. Requiere Java 21 o posterior, y no incluye ninguna biblioteca de diagramas: cada una se instala por separado, y su ruta se indica con una variable como KROKI_DOT_BIN_PATH cuando el ejecutable no está en el PATH. Para la dirección de escucha, prefiera KROKI_LISTEN, ya que la documentación de configuración anuncia que KROKI_PORT se eliminará:

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

La configuración: variables, sin cuentas ni base de datos

Kroki no tiene página de administración, ni cuentas de usuario, ni base de datos: su configuración es un conjunto de variables de entorno, o de propiedades del sistema Java con el jar. En Docker Compose, van en el bloque environment del servicio correspondiente, y después docker compose up -d vuelve a crear el contenedor. Los ajustes que más cuentan para un servidor:

VariableValor por defectoPara qué sirve
KROKI_SAFE_MODEsecureEl nivel de seguridad, detallado más abajo
KROKI_LISTENTodas las interfaces, puerto 8000La dirección y el puerto de escucha; acepta también un socket UNIX, unix:// seguido de una ruta
KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST127.0.0.1Dónde alcanza la pasarela cada complemento; las variables _PORT correspondientes fijan el puerto, y KROKI_DIAGRAMSNET_HOST sirve para diagrams.net
KROKI_COMMAND_TIMEOUT5 segundosLa espera máxima de un ejecutable de diagramas, como dot
KROKI_CONVERT_TIMEOUT20 segundosLa espera máxima de una biblioteca Java, como PlantUML
KROKI_DELEGATE_TIMEOUT_MS30.000La espera máxima de un complemento, en milisegundos
KROKI_MAX_URI_LENGTH4096La longitud de URL aceptada con GET, por encima de la cual Kroki responde 414
KROKI_CONTENT_SECURITY_POLICYscript-src 'none'; object-src 'none'La cabecera Content-Security-Policy enviada con cada respuesta
KROKI_CORS_ALLOWED_HEADERSNinguna adicionalLas cabeceras adicionales permitidas para las llamadas desde otro sitio

Los diagramas Excalidraw producen URL largas. Si aumenta KROKI_MAX_URI_LENGTH, la documentación recomienda no pasar de 8192 caracteres, aunque la mayoría de los navegadores aceptan más en una etiqueta <img>. Para los diagramas más grandes, una petición POST lleva el código en el cuerpo en lugar de en la URL.

Kroki no necesita ningún secreto para funcionar. Dos ajustes opcionales llevan uno: el token KROKI_COMPANION_REGISTRATION_TOKEN, útil si activa el registro de complementos de terceros, que se trata en la sección sobre la protección, y la clave privada de un certificado, si deja que Kroki gestione HTTPS por sí mismo. Manténgalos fuera de cualquier repositorio de código.

HTTPS: el proxy inverso

La pasarela sirve su API en HTTP. Un proxy inverso colocado delante escucha en los puertos 80 y 443, obtiene el certificado de Let’s Encrypt, cifra el tráfico y lo transmite a Kroki en 127.0.0.1:8000. Es también donde se filtra el acceso, como muestra la sección siguiente.

Con Caddy

Caddy obtiene y renueva por sí mismo el certificado del nombre indicado, y su directiva reverse_proxy transmite las cabeceras X-Forwarded-For, X-Forwarded-Proto y X-Forwarded-Host sin ningún ajuste adicional:

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

Con Nginx

Este bloque de sitio escucha en el puerto 80 para que Certbot pueda instalar HTTPS. Dos límites de Nginx se cruzan con los de Kroki: un cuerpo de petición de más de 1 MB se rechaza por defecto con un 413, lo que client_max_body_size ajusta para los diagramas grandes enviados con POST; una línea de petición de más de 8 KB recibe un 414, lo que large_client_header_buffers ajusta si aumenta KROKI_MAX_URI_LENGTH por encima de ese valor.

Bloque 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 sin proxy

La documentación describe también el cifrado por el propio Kroki: KROKI_SSL=true, con el certificado y la clave privada en formato PEM, como texto mediante KROKI_SSL_CERT y KROKI_SSL_KEY, o como archivos mediante KROKI_SSL_CERT_PATH y KROKI_SSL_KEY_PATH. La renovación del certificado se hace entonces a mano, mientras que Caddy o Certbot se encargan de ella por sí solos delante de un proxy.

Proteger una instancia abierta a internet

Kroki no tiene autenticación: cualquiera que llegue a la API puede hacerle generar diagramas. Su protección se apoya, por tanto, en tres elementos, descritos en la documentación y en las notas de versión: el modo de seguridad, los límites de tamaño y de tiempo, y lo que deja pasar el proxy. Empiece por determinar quién necesita llegar a su servidor.

¿Quién llama a su servidor?

El modo de seguridad

KROKI_SAFE_MODE fija tres niveles, cada uno de los cuales incluye las restricciones del anterior. La documentación explica que algunas bibliotecas pueden leer archivos o URL, como las directivas !include de PlantUML, y que Kroki, que no revisa su código, bloquea ese acceso por defecto. Invita a quien gestiona un servidor a elegir el nivel que convenga a su uso.

NivelPara qué sirve
SECURE, por defectoImpide cualquier intento de leer archivos del sistema de archivos o recursos de la red
SAFESe apoya en la limpieza de las peticiones que hace el modo seguro propio de cada biblioteca
UNSAFEDesactiva todas las funciones de seguridad

En una instancia pública, mantenga SECURE. La cabecera Content-Security-Policy, enviada por defecto desde la 0.36.0, completa esta defensa: un script deslizado en un SVG no se ejecuta en el origen de Kroki, ni siquiera cuando la imagen se abre directamente.

Los límites de tamaño y de tiempo

Los tiempos de espera de la tabla de configuración acotan cada conversión. Los complementos añaden los suyos, pensados contra el agotamiento de recursos:

Restringir el acceso en el proxy

Cuando solo su cadena de publicación llama a Kroki, lo más sencillo es aceptar únicamente su dirección IP. Con Caddy, el comparador remote_ip selecciona las demás direcciones, y respond les devuelve 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, las directivas allow y deny del bloque location hacen el mismo trabajo, y gana la primera regla que coincide:

Bloque Nginx, dentro de location /
allow 203.0.113.10;
deny all;

La autenticación básica del proxy es la otra vía: basic_auth con Caddy, cuya contraseña se cifra con caddy hash-password, o auth_basic y un archivo creado con htpasswd con Nginx. Conviene a los clientes que envían las credenciales en cada llamada, como curl -u; para una cadena de documentación, compruebe que su herramienta puede transmitirlas. Para una instancia que sigue siendo pública, Nginx puede además limitar el número de peticiones por dirección IP con su módulo limit_req, ajustado al número de diagramas de sus páginas.

Los complementos de terceros

Kroki puede acoger complementos de terceros que se registran mediante la API /services. Este descubrimiento está desactivado por defecto, y siempre permanece desactivado en modo SECURE. Si lo activa con KROKI_ENABLE_COMPANION_DISCOVERY=true, la documentación pide mantener /services en una red de confianza, y recomienda encarecidamente el token KROKI_COMPANION_REGISTRATION_TOKEN: sin él, Kroki advierte al arrancar de que cualquier cliente de la pasarela puede registrar un complemento.

Conectar Asciidoctor, MkDocs y otras herramientas

Asciidoctor Kroki y el plugin de MkDocs apuntan por defecto a https://kroki.io. Solo necesitan la URL de su servidor, con el prefijo https:// incluido.

Asciidoctor y Antora

La extensión Asciidoctor Kroki lee el atributo kroki-server-url, en la cabecera del documento, en la línea de comandos o en el playbook de Antora. Añada kroki-fetch-diagram para descargar las imágenes al compilar en lugar de que el HTML apunte a su servidor; esta opción requiere un modo seguro de Asciidoctor igual a server o inferior.

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

MkDocs

El plugin mkdocs-kroki-plugin lee server_url, que toma por defecto la variable de entorno KROKI_SERVER_URL. Con http_method: POST, las imágenes se guardan junto a cada página en el sitio compilado, y se conservan en caché entre dos compilaciones:

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

Otras integraciones

La página de herramientas de terceros de la documentación enumera también GitLab, que genera los diagramas Kroki en Markdown, AsciiDoc, reST y Textile, Sphinx, Jekyll, Hugo, Remark, Python-Markdown, MediaWiki, extensiones para Visual Studio Code e IntelliJ, y Kroki.jl para Julia. Cualquier cliente HTTP sirve también, como en este ejemplo de la documentación:

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

Las copias de seguridad: la configuración, ningún dato

Kroki no tiene estado: no conserva nada entre dos peticiones, e incluso el registro de complementos de terceros desaparece tras un reinicio. El código de sus diagramas vive en sus repositorios de documentación, y sus imágenes en sus sitios compilados. En el servidor Kroki, lo que se copia es su configuración:

ElementoLo que guardaCopiarlo
compose.yamlLas imágenes, sus etiquetas y las variables KROKI_*Sí
El archivo .env, si existeLas variables guardadas fuera de compose.yaml, como un token o un certificadoSí, en un lugar seguro
La configuración del proxyEl Caddyfile o el bloque Nginx, y el archivo de contraseñasSí
Las imágenes DockerEl propio softwareNo: docker compose pull las vuelve a descargar
Terminal, en la carpeta del compose.yaml
tar -czf kroki-config-$(date +%F).tar.gz compose.yaml /etc/caddy/Caddyfile

Adapte la lista a su proxy, haga una nueva copia tras cada cambio de configuración y envíela fuera del servidor. Colocada en su disco, entra también en sus copias de seguridad nocturnas. Una restauración consiste en volver a colocar estos archivos y ejecutar docker compose up -d.

Las actualizaciones

Con etiquetas fijadas, cambie la versión de las cuatro imágenes en compose.yaml y después, desde su carpeta:

Terminal
docker compose pull
docker compose up -d

Kroki sigue el versionado semántico, y cada versión publica sus cambios en CHANGELOG.md y en su página de versión. Léalos antes de actualizar, en especial su sección «Security»: la 0.35.0 del 5 de noviembre de 2026 y la 0.36.0 del 9 de noviembre de 2026 corrigen ejecuciones remotas de código mediante los diagramas Bytefield y TikZ, fallos XSS en GoAT y DBML, y falsificaciones de peticiones del lado del servidor mediante BlockDiag y los complementos. En una instancia abierta, despliegue estas versiones sin esperar.

La versión 0.36.0 añade también la cabecera Content-Security-Policy por defecto y el motor de disposición TALA para D2. Para la instalación manual, documenta Java 21 como versión mínima.

Quién hace qué en un VPS administrado

El autoalojamiento exige mantener el servidor además de la aplicación. En un VPS administrado, nuestros equipos se encargan del servidor y siguen su instancia de forma proactiva; Kroki sigue siendo su software, con su configuración y sus complementos.

TemaNuestros equiposUsted
El servidorActualizaciones del sistema y de seguridad, con intervenciones en el servidor incluidasEl momento que mejor convenga a su actividad
La supervisiónServidor vigilado las 24 horas del día, los 7 días de la semana, con intervención sin esperar su llamadaLa lectura de los registros de su instancia
KrokiSeguimiento proactivo: errores, lentitud, memoria de los complementos y espacio en disco detectados, corrección recomendadaSu instalación, sus actualizaciones y sus ajustes, que aplica usted o su asistente de IA
Los diagramas y el accesoEl servidor que los genera, vigilado y con copias de seguridadEl modo de seguridad, los complementos, los límites y las reglas de acceso del proxy
Las copias de seguridadCada noche, cifradas y guardadas fuera de la máquina; restauración incluidaLas copias de su configuración que guarda en otro lugar, y la petición de restauración, cuando la necesite
La migraciónSu servidor actual migrado, gratisEl momento del cambio

Si prefiere que nuestros equipos intervengan en la propia aplicación, ese servicio se factura por horas o a precio cerrado, con un presupuesto comunicado antes de la intervención.

Kroki, en un servidor que cuidamos por usted

Con un VPS administrado de Simafri, nuestros equipos mantienen actualizado el servidor de su instancia de Kroki, lo vigilan día y noche e intervienen sin esperar su llamada; también siguen su instancia de forma proactiva y le recomiendan las correcciones útiles, que aplica usted o su asistente de IA. Las copias de seguridad se cifran cada noche y se guardan fuera de la máquina, su restauración está incluida, y la migración de su servidor actual es gratuita.

Descubrir los VPS administrados

Preguntas frecuentes

¿Kroki es gratuito para una empresa?

Sí. Kroki tiene licencia MIT: puede usarlo, modificarlo y redistribuirlo en su empresa sin ninguna licencia que comprar, siempre que conserve su aviso de copyright. Queda el coste del servidor que lo ejecuta.

¿Necesito los contenedores complementarios de Kroki?

Solo para los diagramas que generan. La imagen yuzutech/kroki basta para PlantUML, GraphViz, D2, Structurizr y la mayoría de los formatos. Mermaid, BPMN, Excalidraw y diagrams.net necesitan cada uno su complemento, conectado mediante KROKI_MERMAID_HOST, KROKI_BPMN_HOST, KROKI_EXCALIDRAW_HOST o KROKI_DIAGRAMSNET_HOST.

¿Cómo instalar Kroki con Docker Compose?

Cree un compose.yaml con la imagen yuzutech/kroki, su puerto 8000 publicado en 127.0.0.1, y los complementos que necesite, como yuzutech/kroki-mermaid, conectados mediante las variables KROKI_*_HOST. Ejecute docker compose up -d, compruebe /health y coloque después un proxy inverso en HTTPS delante del puerto 8000.

¿Kroki tiene una cuenta de administración?

No, Kroki no tiene cuentas, ni página de administración, ni base de datos. Su configuración es un conjunto de variables de entorno KROKI_*, y el acceso a la API se controla en el proxy inverso, por dirección IP o con autenticación básica.

¿Cómo proteger una instancia pública de Kroki?

Mantenga el modo SECURE, activo por defecto, que impide a las bibliotecas leer archivos o la red. Conserve los límites de tiempo y de tamaño, actualice en cuanto una versión corrija una vulnerabilidad y, si solo su cadena de publicación llama a Kroki, acepte únicamente su dirección en el proxy.

¿Cómo usar mi servidor Kroki con Asciidoctor o MkDocs?

Con Asciidoctor, indique la URL de su servidor en el atributo kroki-server-url, y kroki-fetch-diagram para descargar las imágenes al compilar. Con MkDocs, indique server_url en la configuración del plugin kroki, y http_method: POST para guardar las imágenes con el sitio.

¿Qué hay que copiar en un servidor Kroki?

Solo su configuración: compose.yaml, el archivo .env si existe y la configuración del proxy inverso. Kroki no conserva ningún dato, y sus imágenes Docker se vuelven a descargar con docker compose pull.

¿Un VPS administrado cubre Kroki?

Un VPS administrado cubre el servidor: sistema, seguridad, supervisión y copias de seguridad. Nuestros equipos siguen también su instancia de forma proactiva y le recomiendan las correcciones útiles, que aplica usted. Una intervención en la aplicación se factura por horas o a precio cerrado.

Fuentes y documentación oficial

Contáctenos