On-Premise installation

Upgrade Guide

How to upgrade between versions

How to Upgrade

Upgrading Carbone is usually a simple process, as most steps are managed automatically.

First, review our comprehensive Breaking Changes guide.
Then, if needed, follow the step-by-step instructions that match your Carbone deployment method:

Your Environment	Upgrade Steps
Cloud	Change the API version
On-Premise binary	Install the new binary as you would during a standard installation. Carbone keeps your existing directories (templates, config, database, ...).
On-Premise with Docker	Ensure your templates and (optional) database are stored on persistent storage. Then pull the new image.

Breaking Changes

We strive to avoid introducing breaking changes to your templates.
However, certain breaking changes may occur in plugins or the Studio Web Component.

The table below provides a quick overview of what to check when upgrading Carbone.

Version	Breaking changes
`v3.x.x`	No.
`v4.x.x`	No. See notes 1 and 2 below.
`v5.0.x`	No. See notes 1 and 2 below. Also review the new template ID concept.
`v5.1.0`	Avoid this version if you use the Studio Web Component
`v5.1.1`	Breaking changes in the Studio Web Component only.
`v5.4.0`	No. `databaseName` is renamed `templateMetadataFile` and still works.
`v5.12.0`	On-Premise cluster only. Maximum message size between peers is 60 MB instead of 100 MB.
`v5.14.4`	Formatter limits make the generation fail. Authentication errors return `401` instead of `500`.
`v5.16.0`	On-Premise only. New default `securityLevel`, which can block requests to your local network. All editions: `:formatC` prints the ISO 4217 number of decimals by default.

Note 1. Carbone now detects more syntax errors than before. Some templates that previously worked with unusual or undocumented syntax may now produce errors that need to be fixed.

Note 2. The Docker images (On-Premise) and Cloud Edition now use the latest converters (LibreOffice, OnlyOffice, Chrome) available at the time of the Carbone release, which generally improves DOCX/ODT to PDF conversion. However, we recommend verifying that your documents are converted correctly. In our experience, conversions work reliably when documents are properly designed and do not use unusual formatting or design workarounds. For reference, the Cloud API v5 uses LibreOffice 25.2 while Cloud v4 uses LibreOffice 7.5, so DOCX to PDF output can differ when moving from v4 to v5.

Please find more information about our Release Lifecycle here and Force Carbone v5 to behave like v4.

v5.15 -> v5.16

New default security level (On-Premise)

Since v5.16.0, the default securityLevel is 1084 instead of 0. Carbone Cloud was already at the highest level.

1084 = 4 + 8 + 16 + 32 + 1024 activates:

Value	Effect
4	LibreOffice features that are useless on a server are disabled (crash reports, automatic font and extension installation...).
8	Scripts and macros are never executed by LibreOffice.
16	LibreOffice no longer downloads the external links of documents (remote images...).
32	LibreOffice refuses exotic file formats (AbiWord, StarOffice XML, Hangul Office, legacy Mac Office...).
1024	Outgoing traffic to a local network is blocked.

The value 1024 can break an existing installation. Images, :attachFile, :appendFile, :appendTemplate, the resources of an HTML page converted by Chrome, and webhooks are refused if their URL points to a local network (localhost, 127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x), or to a hostname that resolves to a local address (internal DNS name, Docker or Kubernetes service name...).

A refused hostname returns the same error as a hostname which does not exist (ENOTFOUND), so internal DNS names cannot be discovered. Start Carbone with DEBUG=carbone:egress to print the real reason of each refused request.

If your templates, HTML pages or webhooks use a local network, choose one of these options:

Recommended: keep the LibreOffice hardening and only allow the local network with 60 (= 4 + 8 + 16 + 32).
Restore the exact behavior of previous versions with 0.

# Environment variable
export CARBONE_SECURITY_LEVEL=60
# config/config.json
{ "securityLevel": 60 }

Currency decimals

Since v5.16.0, :formatC uses the number of decimals of the ISO 4217 standard by default. The output changes for these currencies:

Currency	Decimals before	Decimals now
JPY, KRW, VND, CLP, PYG, ISK, UGX, BIF, DJF, GNF, KMF, RWF, VUV, XOF, XPF	2	0
JOD, LYD	2	3
TWD, KHR, MOP, MGA	1	2

Example: {d.price:formatC} with 1234.5 in JPY prints ¥1,235 instead of ¥1,234.50. To keep the previous output, set the precision explicitly, for example {d.price:formatC(2)}.

v5.14 -> v5.14.4

Formatter limits

Since v5.14.4, some formatter arguments are limited. Above the limit, the value is rejected instead of being silently reduced:

Formatter	Limit	Result above the limit
`:formatN`, `:formatC`	40 decimals	The generation fails: `The number of decimals cannot be greater than 40`
`:padl`, `:padr`	Target length of 10000	The generation fails: `The target length cannot be greater than 10000`
`:barcode`	`width` and `height`: 1000 mm each. `textsize`: 100 pt	The option is ignored and its default value is used.
`:barcode`	25 million pixels for the final image, `scale` included	The barcode is replaced by the error image.

Authentication errors

Since v5.14.4, an authentication failure other than a missing or expired token returns 401 with the generic message Unauthorized Access: Invalid API key or access token., instead of a 500 with internal details. The detailed reason is only printed in the server log.

v5.11 -> v5.12

Message size between peers

Since v5.12.0, the maximum WebSocket message size between cluster peers (peerPort / peerEndpoints) is maxDataSize (CARBONE_MAX_DATA_SIZE, default 60 MB), instead of a fixed 100 MB. If your peers exchange larger messages, increase maxDataSize.

v5.3 -> v5.4

Template metadata file name

Since v5.4.0, databaseName (CARBONE_DATABASE_NAME) is renamed templateMetadataFile (CARBONE_TEMPLATE_METADATA_FILE, default metadata.db). The old parameter still works: when it is set, it enables templateManagement and its value becomes the metadata file name. If both are set, the new parameter wins.

Do not replace CARBONE_DATABASE_NAME=mydb.sqlite by CARBONE_TEMPLATE_MANAGEMENT=true alone. Carbone then looks for metadata.db and its flushed copies (.metadata.db.0, .metadata.db.1), and does not find your existing template metadata.

Keep the file name:

export CARBONE_TEMPLATE_MANAGEMENT=true
export CARBONE_TEMPLATE_METADATA_FILE=mydb.sqlite

v5.0 -> v5.1.1

Applies only if you use the Embedded Studio Web Component.

Studio Web Component

New embedded modes

Please carefully review the two execution modes of the Studio Web Component.

By default, the studio starts in "embedded" mode, as in version 5.0. However, note that in 5.1.1, the "Save" button has been removed from this mode.

Function changes

The function openTemplate(templateObj, options) is now deprecated and has been replaced in version 5.1.1.

Suppose you have these initial constants:

const _previewOptions = {
  data : {}
}
const _templateObject = {
  templateId : '212121212121212',
  extension  : 'docx',
  comment    : 'file name'
}

If your code currently uses:

studio.openTemplate(_templateObject, _previewOptions);

Update it as follows for Carbone Studio 5.1.1 and above:

// First, set the preview options:
studio.setRenderOptions(_previewOptions, false);
// Then, open the template by its version ID and type:
studio.openTemplateVersionId(_templateObject.templateId, _templateObject.extension, _templateObject);

Or use one of the 5 new ways to open a template. This ensures forward compatibility and uses the new recommended API.

Event changes

// The event is triggered for additional user interactions (such as language, timezone, converter, currency).
// These extra attributes are now included in the 'options:updated' event in 5.1.x and above.
studio.addEventListener('options:updated', (e) => {
  console.log('options:updated', e.detail);
  // {
  //   data           : Object|Array,
  //   complement     : Object|Array,
  //   enum           : Object,
  //   translations   : Object,
  // 
  // ADDITIONAL ATTRIBUTES IN 5.1:
  //   lang           : String,
  //   timezone       : String,
  //   converter      : String,
  //   currencySource : String,
  // }
});


// Carbone now always returns a valid data-URI and createdAt.
// In Carbone 5.0, it sometimes returned a plain base64 string (without the data-URI prefix).
studio.addEventListener('template:updated', (e) => {
  console.log('template:updated', e.detail);
  // AFTER 5.1.x
  // {
  //   createdAt : 1767108187,
  //   type      : "html",
  //   dataURI   : "data:text/html;base64,PCFET0NUWVBFIGh0bWw+PGh0bWw+PGJvZHk+PGRpdj5hemRhemQ8L2Rpdj48L2JvZHk+PC9odG1sPg=="
  // }

  // BEFORE 5.0.x
  // {
  //   type      : "html",
  //   dataURI   : "PCFET0NUWVBFIGh0bWw+PGh0bWw+PGJvZHk+PGRpdj5hemRhemQ8L2Rpdj48L2JvZHk+PC9odG1sPg=="
  // }
});

// Since Carbone v5.1, a reference to the complete internal template object is returned (with the same attributes as the Template HTTP API).
// This object should be cloned before any modification, as it is a direct reference.
// Internal fields starting with "_" may exist and could be hidden or renamed in future versions.
studio.addEventListener('template:saved', (e) => {
  console.log('template:saved', e.detail);
  // AFTER 5.1.x
  // {
  //    versionId   : "a53593973e6ec37c2b79fb9128cc602c830afbb44de4bd0db719b0b71e34fc77",
  //    id          : "1317319105326582256",
  //    createdAt   : 1767109431,
  //    expireAt    : 0,
  //    deployedAt  : -1,
  //    size        : 66,
  //    type        : "html",
  //    name        : "My Template",
  //    comment     : "",
  //    tags        : [],
  //    origin      : 1,
  //    sample      : [
  //      {
  //          "data": {},
  //          "complement": {},
  //          "enum": {},
  //          "translations": {}
  //      }
  //    ],
  // }

  // BEFORE 5.0.x
  // {
  //   "templateId": "424242424242424242424242424",
  //   "extension": "docx"
  // }
});