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.

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.

Please find more information about our Release Lifecycle here.

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"
  // }
});