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 SQLite [if enabled] with embedded database replication/backup.

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

Execution modes

By default, Carbone starts without a database in Stateless mode (document generation only).

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 + SQLite database 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: requires explicit configuration to enable Carbone’s SQLite database with the env variable: CARBONE_DATABASE_NAME=database.sqlite, or the JSON configuration file "databaseName": "database.sqlite". 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 (no versioning)
Embed Studio (with versioning)
External storage plugins (S3, ...)

SQLite Database

Carbone keeps the (optional) database intentionally simple and operationally easy to manage.

The SQLite database contains only two tables:

• templates
• templates_patches

Carbone replication is leaderless (no master node) and designed to avoid single points of failure.
All nodes can accept writes (multi-writer). Short-lived divergences can occur during concurrent updates or network partitions, but replicas automatically converge once connectivity is restored.