---
source: https://carbone.io/documentation/developer/on-premise-installation/configuration.html
title: "Configuration parameters"
description: "Carbone On-Premise configuration options reference"
generated_at: "2026-07-13"
---

# Configuration parameters

Carbone On-Premise configuration options reference

## Overview

This page documents every Carbone On-Premise configuration parameter, grouped by purpose (see the table of contents to jump to a group).

A parameter can be provided three ways. When the same option is set in more than one, the higher-priority source wins:

-   [CLI options](#how-to-set-parameters-cli-example) (highest priority)
-   [Environment variable](#how-to-set-parameters-environment-variable-example)
-   [Configuration file](#how-to-set-parameters-configuration-file-example) (lowest priority)

See [How to set parameters](#how-to-set-parameters) for the exact syntax of each.

> ℹ️ **Note:** Parameters are read once, when the server starts, so restart Carbone to apply a change. A few rendering defaults set here (language, timezone, currency, translations) can also be overridden per request through the [render API](/documentation/developer/http-api/generate-reports.md), or directly inside a template with [in-template options](/documentation/design/overview/in-template-options.md).

## How to set parameters

### CLI example

To list available options, run the help command, such as:

```bash
./carbone webserver --help
```

Here is an example of passing options to the service:

```bash
./carbone webserver --port 4001 --factories 4 --workdir /var/www/carbone --authentication --studio
```

### Configuration file example

To use a configuration file, `config.json` must be created in the `config` folder. Here is an example of a configuration:

```json
{
  "port": 4001,
  "bind": "127.0.0.1",
  "factories": 4,
  "attempts": 2,
  "authentication": true,
  "studio" : true,
  "studioUser" : "admin:pass" // login:password if authentication is active
}
```

### Environment variable example

Environment variables can be used to define options. The name must be uppercased, start with the prefix `CARBONE_`, and use `UPPER_SNAKE_CASE` (each word separated by an underscore), such as:

```bash
export CARBONE_PORT=3600
export CARBONE_BIND=127.0.0.1
export CARBONE_FACTORIES=4
export CARBONE_WORKDIR=/var/www/carbone
export CARBONE_ATTEMPTS=2
export CARBONE_AUTHENTICATION=true
```

> ℹ️ **Note:** Coming from a pre-v5 setup? The old `CARBONE_EE_*` variable names still work. See [Legacy environment variables (before v5)](#legacy-environment-variables-before-v5) for the full old-to-new mapping.

## Server

## Service Port

Port used by Carbone to expose HTTP API

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_PORT` | `--port / -p` | `port` | 4000 |

## Bind

Local IP address the Carbone HTTP server listens on. The default `127.0.0.1` accepts connections from the local machine only. Set it to `0.0.0.0` to listen on all network interfaces, for example when running in Docker or behind a reverse proxy or load balancer.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_BIND` | N/A | `bind` | 127.0.0.1 |

## Workspace directory

Define the place to store elements, it creates 5 directories:  
\- `template` : where carbone keeps templates (cache)  
\- `render` : temp directory where reports are generated,  
\- `asset` : for internal use only,  
\- `config` : config, licenses and ES512 keys for authentication, and  
\- `plugin` : where to put custom plugins

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_WORKDIR` | `--workdir / -w` | `workdir` | `pwd` or `/app` for docker image |

## Licensing

## License directory

Absolute directory path to license.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_LICENSE_DIR` | `--licenseDir / -L` | `licenseDir` | config/ |

## License

License as a string, if the option is used, `licenseDir` option is skipped

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_LICENSE` | `--license / -l` | `license` |   |

## Studio

## Enable Studio

Enable Web interface to preview reports.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_STUDIO` | `--studio / -s` | `studio` | false |

## Studio basic authentication

If the authentication option is enabled, the browser requests an authentication to access the web page. Credentials have to be formatted, such as: `[username]:[password]`

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_STUDIO_USER` | `--studioUser / -S` | `studioUser` | admin:pass |

## Authentication

## Authentication

Enable authentication on Carbone API.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_AUTHENTICATION` | `--authentication / -A` | `authentication` | false |

## Authentication public key

From Carbone v5, you can set a public key for authentication

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_AUTHENTICATION_PUBLIC_KEY` | N.A | N/A |   |

## Document conversion

## Thread number

Multithread parameter, number of Libreoffice, Onlyoffice or Chromium converters

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_FACTORIES` | `--factories / -f` | `factories` | 1 |

## Conversion retry

If `Document Converter` fails to convert one report, the `attempts` option sets the number of retries.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_ATTEMPTS` | N/A | `attempts` | 1 |

## Maximum generation time

Maximum allowed time to generate one document, including the conversion with the LibreOffice, OnlyOffice, or Chrome converters (unit: ms). This is the recommended option.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_GENERATION_TIME` | N/A | `maxGenerationTime` | 60000 |

**Legacy: conversion timeout.** Before `v5.0.4`, this option was named `converterFactoryTimeout` (maximum conversion/socket timeout for one render, unit: ms). It is still supported for backward compatibility, but `maxGenerationTime` supersedes it, so set only one of them.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_CONVERTER_FACTORY_TIMEOUT` | N/A | `converterFactoryTimeout` | 60000 |

## LibreOffice path

Path to the LibreOffice executable used for document conversion. The expected format is `"sofficeExecPath, pythonExecPath"`.

-   `auto`: Carbone automatically detects the LibreOffice installation path (default).
-   Empty String: Disables the LibreOffice converter.
-   Absolute path: Use a custom installation path.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_LIBRE_OFFICE_PATH` | N/A | `libreOfficePath` | `auto` |

## OnlyOffice path

Path to the OnlyOffice executable used for document conversion. The expected format is `"x2tPath, AllFontsPath, fontPath"`.

-   Empty String: Disables the OnlyOffice converter (default).
-   Absolute Path: Use a custom installation path.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_ONLY_OFFICE_PATH` | N/A | `onlyOfficePath` | `''` |

## Chromium path

Path to the Chromium executable used for HTML to PDF conversion.

-   Empty string: Disables the Chromium converter (default).
-   Absolute Path: Use a custom installation path.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_CHROME_PATH` | N/A | `chromePath` | `''` |

## PDF post-compression

When `true`, Carbone runs a post-compression step that can reduce the final file size by up to 3x when several PDFs are concatenated into a single PDF, such as with `:appendTemplate`, `:appendFile`, or batch processing to a single PDF output. It avoids duplicating embedded assets (fonts, images) shared across the merged documents.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_PDF_POST_COMPRESSION` | N/A | `pdfPostCompression` | false |

## Xlsm support

Accept xlsm export

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_XLSM_ENABLED` | `--xlsmEnabled / -xe` | `xlsmEnabled` | false |

## External file downloads

## File download timeout

Maximum allowed time to download a file or an image from an external URL (used by `:appendFile`, `:appendTemplate`, and image URLs). Unit: ms.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_DOWNLOAD_FILE_TIMEOUT` | N/A | `maxDownloadFileTimeout` | 6000 (6s) |

## Concurrent file downloads

Maximum number of concurrent file downloads from external URLs (used by `:appendFile` and `:appendTemplate`).

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_DOWNLOAD_FILE_CONCURRENCY` | N/A | `maxDownloadFileConcurrency` | 15 |

> ℹ️ **Note:** When a template uses `:appendTemplate` (or another internal request), Carbone automatically caps the concurrency at the number of converter factories (`factories`) to avoid converter starvation.

## Concurrent image downloads

Maximum number of concurrent image downloads from external URLs when rendering a report.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_DOWNLOAD_IMAGE_CONCURRENCY` | N/A | `maxDownloadImageConcurrency` | 15 |

## Maximum number of downloaded files

Maximum number of files downloaded from external URLs for a single render (used by `:appendFile` and `:appendTemplate`).

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_DOWNLOAD_FILE_COUNT` | N/A | `maxDownloadFileCount` | 20 |

## Maximum total size of downloaded files

Total maximum size limit for all files downloaded from external URLs combined, for a single render (used by `:appendFile`). The value must be in **bytes**. Calculation example: 10 \* 1024 \* 1024 = 10MB

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_DOWNLOAD_FILE_SIZE_TOTAL` | N/A | `maxDownloadFileSizeTotal` | 10485760 (10MB) |

## Limits & security

## Maximum data size

Maximum JSON data size accepted when rendering a report, the value must be in **bytes**. Calculation example: 100 \* 1024 \* 1024 = 100MB

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_DATA_SIZE` | `--maxDataSize / -mds` | `maxDataSize` | 62914560 (60MB) |

## Maximum template size

The file size limit when uploading a new template through the request `POST /template`, the value must be in **bytes**. Calculation example: 30 \* 1024 \* 1024 = 30MB

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_TEMPLATE_SIZE` | N/A | `maxTemplateSize` | 20971520 (20MB) |

## Maximum template uncompressed size

Maximum total uncompressed size allowed for a template archive (zip bombing protection). The value must be in **bytes**. Calculation example: 200 \* 1024 \* 1024 = 200MB

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_TEMPLATE_UNCOMPRESSED_SIZE` | N/A | `maxTemplateUncompressedSize` | 209715200 (200MB) |

## Maximum number of reports per batch

Max number of reports in a batch when batchSplitBy is used. If equal 0, batch processing is disabled and returns an error

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_NB_REPORT_MAX_PER_BATCH` |   | `nbReportMaxPerBatch` | 100 |

## Maximum repetition factor

Maximum repetition factor allowed in loops, for example `{d[i+1*qty]}`. It protects against excessive expansion during rendering.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_MAX_REPETITION_FACTOR` | N/A | `maxRepetitionFactor` | 400 |

## Security level

Bit field used to activate API security features (for example, restricting template IDs to 64-hexadecimal characters, or enforcing multi-tenant access). 0 disables the extra restrictions.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_SECURITY_LEVEL` | `--securityLevel` | `securityLevel` | 0 |

## Localization

## Language

Locale language used by Carbone

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_LANG` | `--lang / -l` | `lang` | en |

## Timezone

Timezone for managing dates

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TIMEZONE` | `--timezone / -t` | `timezone` | Europe/Paris |

## Source currency

Currency source for money conversion. If empty, it depends on the locale.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_CURRENCY_SOURCE` | `--currencySource / -cs` | `currencySource` |   |

## Target currency

Currency target for money conversion. If empty, it depends on the locale.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_CURRENCY_TARGET` | `--currencyTarget / -ct` | `currencyTarget` |   |

## Translation dictionary

Translation object loaded at startup. It can be overwritten by rendering requests. The option can only be set on the `config/config.json` file.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| N/A | N/A | `translations` | `{}` |

## Storage retention & cleanup

## Template retention time

Template path retention in days. 0 means infinite retention.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_PATH_RETENTION` | `--templatePathRetention / -r` | `templatePathRetention` | 0 |

## Render retention time

Render path retention in minutes when a report is not downloaded. 0 means infinite retention (uses the file modified time).

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_RENDER_PATH_RETENTION` | N/A | `renderPathRetention` | 50 |

## Cleaning interval

Time interval to clean the `/template` and `/render` directories (unit: minutes).

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_CLEAN_INTERVAL_TIME` | `--cleanIntervalTime / -ci` | `cleanIntervalTime` | 10 |

## Template management

## Template management

Enable template metadata state tracking (categories, tags, versions, and related metadata). See the [Template management](/documentation/developer/on-premise-installation/template-management.md) guide for versioning, metadata storage and clustering.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_MANAGEMENT` | N/A | `templateManagement` | false |

## Template metadata file

Filename of the template metadata store, kept inside the `/template` storage.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_METADATA_FILE` | N/A | `templateMetadataFile` | metadata.db |

## Template metadata flush schedule

Cron expression used to persist the template metadata on disk (in the `/template` directory).

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_METADATA_FLUSH_CRON` | N/A | `templateMetadataFlushCron` | `0 0 * * *` |

## Template metadata flush on exit

Flush the template metadata to disk (and external storage) when a node shuts down.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_METADATA_FLUSH_ON_EXIT` | N/A | `templateMetadataFlushOnExit` | true |

## Template metadata patch retention

How long (in hours) each node keeps the synchronisation patch sets used to catch up peers. Must be greater than the interval between two flushes.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_TEMPLATE_METADATA_PATCH_RETENTION_HOURS` | N/A | `templateMetadataPatchRetentionHours` | 25 |

## Clustering

## Peer port

Internal port used for conflict-free metadata synchronisation between cluster nodes. It also serves the [`/metrics`](/documentation/developer/on-premise-installation/metrics.md) endpoint and enables the [job balancer](#job-balancer). Leave it empty on a standalone node. See [HA and Scaling](/documentation/developer/on-premise-installation/ha-and-scaling.md#high-availability-and-clustering).

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_PEER_PORT` | N/A | `peerPort` |   |

## Peer endpoints

Comma-separated addresses of the other cluster peers. Each entry is a **hostname** (a domain name, a Docker container name, or a Kubernetes service name) or an IP address, optionally followed by `:port` (no `ws://` scheme needed). Carbone resolves each hostname through the OS DNS and uses every returned IP as a peer, so a headless Kubernetes service expands to all of its pods. Without a port, it reuses `peerPort`.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_PEER_ENDPOINTS` | N/A | `peerEndpoints` |   |

## Job balancer

Spread document conversion load across the peers of a cluster to smooth out conversion spikes without an external load balancer. It only activates when the internal cluster channel is enabled (template management + `peerPort` + `peerEndpoints`). See the [HA and Scaling](/documentation/developer/on-premise-installation/ha-and-scaling.md#job-balancer) guide for how it works, requirements, and monitoring.

| Env. Variable | CLI option | config.json parameter | Default value |
| --- | --- | --- | --- |
| `CARBONE_JOB_BALANCER` | N/A | `jobBalancer` | false |

## Legacy environment variables (before v5)

Before Carbone v5, environment variables used the prefix `CARBONE_EE_` followed by the **parameter name in uppercase with no separators** (for example `CARBONE_EE_STUDIOUSER`). Since v5, they use the `CARBONE_` prefix with `UPPER_SNAKE_CASE` (for example `CARBONE_STUDIO_USER`).

**Both formats are still accepted, so an existing `CARBONE_EE_*` setup keeps working without changes.** If the same option is set in both formats, the new `CARBONE_` name takes precedence. The table below maps the most common legacy names to their current equivalent.

| Before v5 | Since v5 |
| --- | --- |
| `CARBONE_EE_PORT` | [`CARBONE_PORT`](#service-port) |
| `CARBONE_EE_BIND` | [`CARBONE_BIND`](#bind) |
| `CARBONE_EE_WORKDIR` | [`CARBONE_WORKDIR`](#workspace-directory) |
| `CARBONE_EE_FACTORIES` | [`CARBONE_FACTORIES`](#thread-number) |
| `CARBONE_EE_ATTEMPTS` | [`CARBONE_ATTEMPTS`](#conversion-retry) |
| `CARBONE_EE_AUTHENTICATION` | [`CARBONE_AUTHENTICATION`](#authentication) |
| `CARBONE_EE_STUDIO` | [`CARBONE_STUDIO`](#enable-studio) |
| `CARBONE_EE_STUDIOUSER` | [`CARBONE_STUDIO_USER`](#studio-basic-authentication) |
| `CARBONE_EE_LICENSE` | [`CARBONE_LICENSE`](#license) |
| `CARBONE_EE_LICENSEDIR` | [`CARBONE_LICENSE_DIR`](#license-directory) |
| `CARBONE_EE_MAXDATASIZE` | [`CARBONE_MAX_DATA_SIZE`](#maximum-data-size) |
| `CARBONE_EE_MAXTEMPLATESIZE` | [`CARBONE_MAX_TEMPLATE_SIZE`](#maximum-template-size) |
| `CARBONE_EE_CONVERTERFACTORYTIMEOUT` | [`CARBONE_CONVERTER_FACTORY_TIMEOUT`](#maximum-generation-time) |
| `CARBONE_EE_TEMPLATEPATHRETENTION` | [`CARBONE_TEMPLATE_PATH_RETENTION`](#template-retention-time) |
| `CARBONE_EE_RENDERPATHRETENTION` | [`CARBONE_RENDER_PATH_RETENTION`](#render-retention-time) |
| `CARBONE_EE_CLEANINTERVALTIME` | [`CARBONE_CLEAN_INTERVAL_TIME`](#cleaning-interval) |
| `CARBONE_EE_LANG` | [`CARBONE_LANG`](#language) |
| `CARBONE_EE_TIMEZONE` | [`CARBONE_TIMEZONE`](#timezone) |

## 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)
- [On-Premise](/documentation/developer/on-premise-installation/introduction.md)