Template management

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.

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: a SHA-256 hash (with a random salt) of a specific version. It matches the file stored on disk or external storage.
  • 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.

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:

export CARBONE_TEMPLATE_MANAGEMENT=true

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

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.