Skip to content
Klutch.sh Docs

Deploying a Kroki App

Introduction

Kroki is an open-source diagram rendering service that converts textual diagram definitions into images. Deploying Kroki with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and optional persistent storage for cache and assets—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Kroki configuration (GitHub is the only supported git source)
  • Docker familiarity; Kroki runs on JVM and Node components
  • Optional: persistent storage for cache if you want warm renders across deployments

For platform onboarding, see the Quick Start.

Architecture and ports

  • Kroki serves HTTP; set the internal container port to 8000.
  • If you deploy backing tools or caches, run them as separate Klutch.sh TCP apps exposed on port 8000 and connect on native ports.
  • Persistent storage is optional for cache; mount it if you want faster cold starts.

Repository layout

kroki/
├── config/                 # Optional config overrides
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; manage them with Klutch.sh environment variables.

Installation (local) and starter commands

Local test with the official image:

Terminal window
docker run --rm -p 8000:8000 yuzutech/kroki

Optional start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec java -Djava.security.egd=file:/dev/./urandom -jar /opt/kroki/kroki-server.jar

Make it executable with chmod +x start.sh.

Dockerfile for Kroki (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM yuzutech/kroki:0.24.0


WORKDIR /opt/kroki


# Copy custom config if needed
COPY config /opt/kroki/config


EXPOSE 8000
CMD ["java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "/opt/kroki/kroki-server.jar"]

Notes:

  • Pin the image tag for reproducible builds.
  • If you add diagram tools or fonts, extend the image accordingly.

Environment variables (Klutch.sh)

  • PORT=8000
  • KROKI_CACHE_DIR=/opt/kroki/cache (optional if you persist cache)
  • KROKI_MAX_REQUEST_SIZE=1048576 (adjust as needed)
  • Set any tool-specific toggles as env vars if you customize the image.

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo Kroki uses prebuilt image"
  • NIXPACKS_START_CMD=java -Djava.security.egd=file:/dev/./urandom -jar /opt/kroki/kroki-server.jar
  • NIXPACKS_JDK_VERSION=17

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /opt/kroki/cache — optional cache to speed repeated renders.
  • /opt/kroki/config — optional if you edit configs at runtime.

Ensure these paths are writable inside the container.

Deploy Kroki on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Kroki.
  3. Set the internal port to 8000.
  4. Add the environment variables above (cache dir, request size, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /opt/kroki/cache (and /opt/kroki/config if used), selecting sizes that fit your caching needs.
  6. Deploy. Your Kroki service will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample usage

Render a PlantUML diagram via HTTP:

Terminal window
curl -X GET \
  "https://example-app.klutch.sh/plantuml/svg/SoWkIImgAStDuNBCoKnELT2rKt3AJx9pKiX8pSd9oCbCJbMmKiX8pSd9B4bCJbNmKiX8LSZFIyrA0M00"

Health checks and production tips

  • Add a reverse proxy health check to /health (if enabled) or / to verify the service.
  • Enforce HTTPS at the edge; forward HTTP to port 8000 internally.
  • Pin image tags and test upgrades carefully, as diagram tool versions may change outputs.
  • Monitor disk usage if caching; resize volumes before they fill.
  • Keep request size limits and timeouts tuned for your diagrams.

Kroki on Klutch.sh combines reproducible Docker builds with managed secrets, optional persistent cache, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8000 configured, you can deliver fast, reliable diagram rendering without extra YAML or workflow overhead.