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

> Configure Kroki server URL for self-hosted diagram rendering in Astro Big Doc. Set the KROKI_SERVER environment variable to use your private instance for faster, more secure diagram generation.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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.

```javascript
// 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:

```dotenv

# .env (place at the project root)

KROKI_SERVER=http://localhost:8000

```

The [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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:

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

```

### Production and Docker Deployments

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

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

```ts
// 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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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.