--- source: https://carbone.io/documentation/developer/on-premise-installation/introduction.html title: "Use and configure Carbone in your infrastructure" description: "Run Carbone from your environment - Introduction to Carbone On-Premise setup" generated_at: "2026-07-08" --- # On-Premise Run Carbone from your environment - Introduction to Carbone On-Premise setup ## 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](https://carbone.io/changelog.md). - **Docker image**: available on [Docker Hub](https://hub.docker.com/r/carbone/carbone-ee) (`carbone/carbone-ee`). Includes the Carbone binary and all required document converter dependencies. > ℹ️ **Note:** By default, the program runs with free Community features. To use Carbone Enterprise Edition, you need a Carbone license. [Contact us](https://carboneio.pipedrive.com/scheduler/5Rzzbxu6/carbone-on-premiseaws-presentation) 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](/documentation/developer/on-premise-installation/plugins.md) (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](/documentation/developer/on-premise-installation/template-management.md) when template management is enabled. - Optionally, the built-in [job balancer](/documentation/developer/on-premise-installation/ha-and-scaling.md#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: ![Carbone Architecture](/img/doc/carbone-architecture-2.svg) ## 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](/documentation/developer/on-premise-installation/template-management.md) 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](/documentation/design/overview/getting-started.md) | ✓ | ✓ | | [Multitenant](/documentation/developer/embedding/multi-tenancy.md) template isolation | ✓ | ✓ | | [Embed Studio](/documentation/developer/embedding/studio-web-component.md) (without template management) | ✓ | ✓ | | [Embed Studio](/documentation/developer/embedding/studio-web-component.md) (with template management) | ✗ | ✓ | | External storage [plugins](/documentation/developer/on-premise-installation/plugins.md) (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](/documentation/developer/on-premise-installation/template-management.md) for setup and clustering, and [Metrics](/documentation/developer/on-premise-installation/metrics.md) to monitor replication. ## Related topics - [Upgrade Guide](/documentation/developer/on-premise-installation/upgrade-guide.md) - [Template management](/documentation/developer/on-premise-installation/template-management.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) - [Deploy on MacOS](/documentation/developer/on-premise-installation/install-on-macos.md)