How to Configure the Kroki Server URL for Self-Hosted Diagram Rendering in Astro Big Doc

Set the KROKI_SERVER environment variable to your self-hosted instance URL (e.g., http://localhost:8000) before building or running Astro Big Doc, and the project will automatically route all diagram rendering requests to your private Kroki server instead of the public https://kroki.io endpoint.

Astro Big Doc is an open-source documentation framework that renders PlantUML, Mermaid, Graphviz, and other diagrams through the Kroki unified diagram service. While it defaults to the public Kroki instance, production deployments often require air-gapped or self-hosted diagram rendering for security, compliance, or performance reasons.

Understanding the Kroki Integration Architecture

The diagram rendering pipeline in Astro Big Doc separates configuration from execution across two key files.

Configuration Resolution in config.js

In config.js (lines 12-20), the application reads process.env.KROKI_SERVER and falls back to https://kroki.io when the variable is undefined. The resolved value is exported as config.kroki_server for use throughout the application.

// config.js - Environment variable handling
const config = {
  kroki_server: process.env.KROKI_SERVER || 'https://kroki.io',
  // ... other config options
};

Diagram Generation in Kroki.astro

The src/components/markdown/code/Kroki.astro component (lines 15-22) constructs the rendering endpoint by interpolating config.kroki_server with the diagram language and format. It POSTs the raw diagram source to ${config.kroki_server}/${language}/svg/ and receives the rendered SVG in response. Generated diagrams are cached via diagram_cache, but the source URL always reflects the current server configuration.

Configuring the KROKI_SERVER Environment Variable

You can configure the Kroki server URL through environment variables without modifying source code.

Development Setup with .env Files

For local development, create a .env file in the project root:

# .env (place at the project root)

KROKI_SERVER=http://localhost:8000

The config.js file already invokes dotenv.config(), so variables defined here are automatically loaded into process.env.

Command Line Configuration

For Unix-like systems, prepend the variable to your npm commands:

KROKI_SERVER=http://kroki.mycompany.com npm run dev

Production and Docker Deployments

In containerized environments, export the variable before the build process:

export KROKI_SERVER=https://kroki.internal.example.com
npm run build && npm start

Verifying Your Configuration

To confirm which Kroki endpoint is active, inspect the configuration object:

// src/pages/debug.ts
import { config } from '@/config.js';
console.log('Kroki server in use:', config.kroki_server);

Executing this page prints the resolved URL, confirming whether requests will hit your self-hosted instance or the public endpoint.

Summary

• Astro Big Doc uses the KROKI_SERVER environment variable to determine where to render diagrams.
• The default endpoint is https://kroki.io, overridden by setting the environment variable before runtime.
• Configuration is centralized in config.js and consumed by src/components/markdown/code/Kroki.astro.
• No code changes are required to switch between public and self-hosted Kroki instances.

Frequently Asked Questions

What diagram formats are supported with a self-hosted Kroki server?

Astro Big Doc supports all languages defined in src/components/markdown/code/kroki.yaml, including PlantUML, Mermaid, Graphviz, BlockDiag, and others. The self-hosted Kroki instance must have the corresponding diagram engines installed to render specific formats.

Does Astro Big Doc cache diagrams when using a custom Kroki URL?

Yes. The Kroki.astro component implements diagram_cache to store generated SVGs locally. This prevents repeated network requests to your self-hosted server, reducing load and improving build performance regardless of which Kroki endpoint is configured.

Can I use different Kroki servers for development and production?

Absolutely. Set KROKI_SERVER=http://localhost:8000 in your local .env file for development, and use your production server's environment variables (Docker, CI/CD pipelines, or hosting platform settings) to point to https://kroki.production.example.com during builds.

What happens if the KROKI_SERVER variable is not set?

If KROKI_SERVER is undefined, config.js automatically falls back to the public Kroki instance at https://kroki.io. This ensures diagrams render out-of-the-box for new users while allowing enterprise deployments to override the endpoint for compliance or network isolation requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}