---
source: https://carbone.io/documentation/developer/on-premise-installation/template-management.html
title: "Template management"
description: "Enable template versioning and metadata tracking on Carbone On-Premise"
generated_at: "2026-07-07"
---

# Template management

Enable template versioning and metadata tracking on Carbone On-Premise

## Overview

By default, Carbone On-Premise is **stateless**: it renders the template you send, referenced by its **Version ID** (a SHA-256 hash of the file), and keeps no state. This is the same behaviour as Carbone v2, v3 and v4.

Enabling **template management** makes Carbone **stateful**: it tracks template metadata, so you get versioning, stable template IDs, optional metadata, and the full Studio interface.

> ℹ️ **Note:** Since `v5.4`, the documentation and logs use the single term **template management** (previously "stateful vs stateless", "with / without versioning", or "with / without database"; the term "Database" is now "Template metadata").

## What you get

-   **Versioning**: every template has two identifiers:
    -   [**Version ID**](/documentation/developer/http-api/introduction.md#version-id): a SHA-256 hash (with a random salt) of a specific version. It matches the file stored on disk or external storage.
    -   [**Template ID**](/documentation/developer/http-api/introduction.md#template-id): a short, constant 64-bit ID shared by every version. Calling an endpoint with a Template ID (for example `POST /render/{id}`) uses the **latest deployed version**, based on the `deployedAt` timestamp; use a Version ID to target a specific version.
-   **Controlled deployment**: promote a new version to production when you choose, through `deployedAt`.
-   **Template listing and management** through the API.
-   **Optional metadata and sample data** stored with each template (name, comments, and more).
-   **Unified Studio**: Studio runs in its full mode, identical to Carbone Cloud.

> ℹ️ **Note:** With template management enabled, every API endpoint requires the template ID or version ID to be a 64-hexadecimal-character value or a 64-bit number. Other values are rejected.

## Enable it

Set a single boolean:

```bash
export CARBONE_TEMPLATE_MANAGEMENT=true
```

| Env. Variable | config.json parameter | Default value | Description |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_MANAGEMENT` | `templateManagement` | false | Turn template management on. |

> ℹ️ **Note:** Before `v5.4`, it was enabled implicitly via `databaseName` (`CARBONE_DATABASE_NAME`). That parameter is deprecated but still supported and automatically enables `templateManagement`; if both are set, the new parameter wins.

## Metadata storage

The metadata is stored as a special template file inside the `/template` storage, like any other template, and flushed regularly as `.metadata.db.0` (current) and `.metadata.db.1` (previous). With template plugin hooks (`writeTemplate` and `readTemplate`), the same files are also persisted to your external storage as `.metadata.db.0.backup` and `.metadata.db.1.backup`.

| Env. Variable | config.json parameter | Default value | Description |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_METADATA_FILE` | `templateMetadataFile` | metadata.db | Filename of the metadata store. |

## High availability and clustering

Template management runs across a cluster of nodes or Docker containers with **no single point of failure**: nodes replicate their metadata conflict-free and persist it to a shared `/template` volume or external storage. For the cluster setup (peer configuration, metadata replication, startup and shutdown behaviour) and for spreading document conversion load across nodes, see [HA and Scaling](/documentation/developer/on-premise-installation/ha-and-scaling.md).

## Related topics

- [Upgrade Guide](/documentation/developer/on-premise-installation/upgrade-guide.md)
- [On-Premise Requirements](/documentation/developer/on-premise-installation/requirements.md)
- [On-Premise plugins](/documentation/developer/on-premise-installation/plugins.md)
- [Metrics (OpenMetrics)](/documentation/developer/on-premise-installation/metrics.md)
- [On-Premise](/documentation/developer/on-premise-installation/introduction.md)
- [Deploy on MacOS](/documentation/developer/on-premise-installation/install-on-macos.md)