On-Premise

Getting the software

Carbone On-Premise is available in two distribution formats:

• Standalone binary: includes the template engine, web server, and Studio. Available for Linux, macOS, and Windows. Download from the Changelog.
• Docker image: available on Docker Hub (carbone/carbone-ee). Includes the Carbone binary and all required document converter dependencies.

By default, the program runs with free Community features. To use Carbone Enterprise Edition, you need a Carbone license. Contact us to learn more, or request a free 30-day trial in our chat.

Overview

Carbone On-Premise is built for DevOps-friendly deployments: simple to run, easy to scale, and flexible to integrate.

Carbone runs as a single executable binary that embeds the template engine, API server, and Studio.
Only two externals may be customized depending on your needs:

• document converters, included in Docker by default, automatically detected if installed on OS
• optional plugins (JS) for custom logic and integrations (authentication, storage adapters, data processing, etc.)

Carbone scales:

• Vertically: multithreaded rendering on a single host
• Horizontally: multiple instances behind a load balancer, with shared template storage (e.g., filesystem/S3), and replicated template metadata when template management is enabled.
  • Optionally, the built-in job balancer spreads document conversion load across peers to smooth out spikes, without an external load balancer.

The diagram below shows the main components and how requests flow through Carbone:

Execution modes

By default, Carbone starts in Stateless mode (document generation only), without template management.

Depending on your configuration, Carbone can also manage template storage with versioning. The mode you choose depends on where templates are stored and who owns the "source of truth":

Execution mode	Template source of truth	Template storage
Stateless	Your app	None - template sent with each request (base64)
Hybrid	Your app or Carbone	Filesystem, S3 or other
Stateful	Carbone	Filesystem, S3 + template management enabled

How to choose a mode?

• Stateless vs Hybrid: this is not a Carbone configuration. It depends only on how you call the API:

  • Stateless: you send the template with each render request (e.g., base64).
  • Hybrid: you reference a template stored outside of Carbone (filesystem/S3).

• Stateful (also called template management): requires explicit configuration. Enable it with the env variable CARBONE_TEMPLATE_MANAGEMENT=true (or "templateManagement": true in the JSON config file), see the Template management guide. This is the configuration used by Carbone Cloud.

Features per mode

Below is the list of available features for each Carbone Execution Mode:

Features	Stateless or Hybrid	Stateful
	No database (default)	With database
Template Reference
By versionId (= SHA256 template file hash)
By constant 64-bit ID (auto or user-defined)
HTTP API
Upload/Download/Delete template file (disk/S3)
Generate doc from stored template
Generate doc from ephemeral (base64) template
Single call - generate & download
Download generated doc via unique ephemeral link
Store template metadata (name, tags, comments, json sample...)
Track template versions and select the main "deployed" version
Pin rendering to deployed template version
List/search templates
Download/Patch/Delete deployed version
List template categories
List template tags
Other
All template design features
Multitenant template isolation
Embed Studio (without template management)
Embed Studio (with template management)
External storage plugins (S3, ...)

Template metadata

When template management is enabled, Carbone stores template metadata in a simple, embedded SQLite store (default metadata.db).

Replication is leaderless (no master node) and multi-writer: every node accepts writes and replicas automatically converge after concurrent updates or network partitions, with no single point of failure.

See Template management for setup and clustering, and Metrics to monitor replication.