On-Premise installation

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:

See How to set parameters for the exact syntax of each.

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, or directly inside a template with in-template options.

How to set parameters

CLI example

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

./carbone webserver --help

Here is an example of passing options to the service:

./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:

{
  "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:

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

Coming from a pre-v5 setup? The old CARBONE_EE_* variable names still work. See 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".

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".

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.

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

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 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 endpoint and enables the job balancer. Leave it empty on a standalone node. See HA and Scaling.

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 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
CARBONE_EE_BIND CARBONE_BIND
CARBONE_EE_WORKDIR CARBONE_WORKDIR
CARBONE_EE_FACTORIES CARBONE_FACTORIES
CARBONE_EE_ATTEMPTS CARBONE_ATTEMPTS
CARBONE_EE_AUTHENTICATION CARBONE_AUTHENTICATION
CARBONE_EE_STUDIO CARBONE_STUDIO
CARBONE_EE_STUDIOUSER CARBONE_STUDIO_USER
CARBONE_EE_LICENSE CARBONE_LICENSE
CARBONE_EE_LICENSEDIR CARBONE_LICENSE_DIR
CARBONE_EE_MAXDATASIZE CARBONE_MAX_DATA_SIZE
CARBONE_EE_MAXTEMPLATESIZE CARBONE_MAX_TEMPLATE_SIZE
CARBONE_EE_CONVERTERFACTORYTIMEOUT CARBONE_CONVERTER_FACTORY_TIMEOUT
CARBONE_EE_TEMPLATEPATHRETENTION CARBONE_TEMPLATE_PATH_RETENTION
CARBONE_EE_RENDERPATHRETENTION CARBONE_RENDER_PATH_RETENTION
CARBONE_EE_CLEANINTERVALTIME CARBONE_CLEAN_INTERVAL_TIME
CARBONE_EE_LANG CARBONE_LANG
CARBONE_EE_TIMEZONE CARBONE_TIMEZONE