Configuration parameters

Configurable parameters

Carbone default parameters can be overwritten through:

• CLI options (highest priority)
• Environment variable
• Configuration file (lowest priority)

If an option is reported in different places, CLI options are picked in priority, then environment variables in second place, and finally the configuration file.

We recommend that you use the environment variable configuration

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 --attemps 2 --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 has to be uppercased and has to start with the prefix "CARBONE_EE_", such as:

export CARBONE_EE_PORT=3600
export CARBONE_EE_BIND=127.0.0.1
export CARBONE_EE_FACTORIES=4
export CARBONE_EE_WORKDIR=/var/www/carbone
export CARBONE_EE_ATTEMPTS=2
export CARBONE_EE_AUTHENTICATION=true

Enable Studio

Enable Web interface to preview reports.

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_STUDIO	--studio / -s	studio	false

Service Port

Port use by Carbone to expose HTTP API

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_PORT	--port / -p	port	4000

Workspace directory

Define the place to store elements, it creates 6 directories:
- template : where carbone keeps templates (cache)
- render : temp directory where report are generated,
- asset : internal used only,
- config : config, licenses and ES512 keys for authentication,
- logs : [NOT IMPLEMENTED YET] formatted output logs, and
- plugin : where to put custom plugin

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_WORKDIR	--workdir / -w	workdir	pwd or /app for docker image

License directory

Absolute directory path to license.

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_LICENSEDIR	--licenseDir / -L	licenseDir	config/

License

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

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_LICENSE	--license / -l	license

Authentification

Enable authentification on Carbone API.

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_AUTHENTICATION	--authentication / -A	authentication	false

Authentication public key

From Carbone v5, you can set public key for authentication

Env. Variable	CLI option	config file parameter	Default value
CARBONE_AUTHENTICATION_PUBLIC_KEY	N.A	N/A

Studio basic authentication

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

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_STUDIOUSER	--studioUser / -S	studioUser	admin:pass

Thread number

Multithread parameter, number of Libreoffice, Onlyoffice or Chromium converter

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_FACTORIES	--factories / -f	factories	1

Conversion retry

If Document Converter fails to convert one report, attempts options set the number of re-try.

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_ATTEMPTS	--attemps / -a	attempts	1

Conversion timeout

Maximum conversion/socket timeout for one render (unit: ms)

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_CONVERTERFACTORYTIMEOUT	N/A	converterFactoryTimeout	60000

Maximum data size

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

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_MAXDATASIZE	--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 bytes. Calcul example: 30 * 1024 * 1024 = 30MB

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_MAXTEMPLATESIZE	N/A	maxTemplateSize	20971520 (20MB)

Template retention time

Template path retention in days. 0 means infinite retention.

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_TEMPLATEPATHRETENTION	--templatePathRetention / -r	templatePathRetention	0

Language

Locale language used by Carbone

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_EN	--lang / -l	lang	en

Timezone

Timezone for managing dates

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_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 file parameter	Default value
CARBONE_EE_CURRENCYSOURCE	--currencySource / -cs	currencySource

Target currency

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

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_CURRENCYTARGET	--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 file parameter	Default value
N/A	N/A	translations	{}

Xlsm support

Accept xlsm export

Env. Variable	CLI option	config file parameter	Default value
CARBONE_EE_XLSMENABLED	--xlsmEnabled / -xe	xlsmEnabled	false