This page describes a general upgrade procedure. You will find below the list of required manual steps per version. Follow them carefully from your current version to the new version.
- To upgrade from one LTS version to another, from 7.10 to 10.10 for instance, follow 7.10 -> 8.10 -> 9.10 -> 10.10.
- To upgrade from an LTS version to the latest Fast Track version, from 6.0 to 8.3 for instance, follow 6.0 -> 7.10 -> 8.1 -> 8.2, etc.
Each version of the Nuxeo Platform comes with bug fixes, new features and improvements. This means upgrading to the latest public release is a smart move. In order to make upgrade easy, we are very careful not to break anything:
- We don't break the APIs between two versions: we add new APIs and deprecate old ones,
- There are several minor versions between the deprecation and the removal so you have time to adapt your code,
- If we completely replace a service (that was the case for
EventServicefor example), we provide compatibility packages so you can continue using the old API (even if migrating to the new API is highly recommended).
In terms of data migration we are also very careful not to break anything. When some changes or optimizations impact the storage layer we either:
- Make the upgrade automatically,
- Or provide guidelines for the upgrade.
Upgrading is usually a simple and painless process. Using the template system also allows to easily transpose your configuration from one version to an other. In the worse cases, in case of problem, the Nuxeo Support is there to help you :smile:
You should have configured Nuxeo with a specific configuration (and optionally with custom templates) setting a database (for production) and a data directory. In that case, follow the steps below to upgrade your Nuxeo Platform.
Make sure no jobs are still queued or running before starting the upgrade procedure.
- Do a backup.
- Stop the old Nuxeo Platform.
- Deploy the new Nuxeo Platform version (see the Installation pages).
- Update the environment variable
Update your nuxeo.conf file to make it use your custom configuration, database and data directory.
Report your custom configuration (uncommented lines in the old Nuxeo Platform
nuxeo.conf) into the nuxeo.conf file of the target Nuxeo Platform version.sBe very careful about the two properties allowing to configure the backend for audit logs, make sure you read the related documentation:
audit.elasticsearch.enabled: Disabling Elasticsearch for Audit Logs
audit.elasticsearch.migration: Triggering SQL to Elasticsearch Audit Logs Migration
- Replace the old nuxeo.conf file with this new one.
- Upgrade your Nuxeo Packages.
- Upgrade and install your Studio project customization.
- Upgrade and install your custom code.
- If you have manually copied JARs in
$NUXEO/nxserver/bundles(like nuxeo-platform-login-cas2 if you are using the CAS2 authentication), install the corresponding new version of the JARs.
- Start the new Nuxeo Platform.
- Check for
$NUXEO/log/server.log, or Nuxeo Runtime startup errors after log
Nuxeo Platform Started.
nuxeoctl mp-listto get the list of all downloaded and installed (started state) Nuxeo Packages.
- Get the list of all started Nuxeo Packages.
nuxeoctl mp-installon each addon that was in started state at step 2.
To upgrade your Nuxeo Studio project:
- in the Nuxeo Studio Settings, change your target platform from the Application Definition menu.
- In Source Control > Branch Management, click on the Tag button of the last commit (or of the last relevant commit) to save your Studio project state in a new version.
- Install the newly tagged version of your Project on your platform by running
nuxeoctl mp-install StudioProjectName-tagName.
The XML extensions contributed in Nuxeo Studio are not processed by the Studio upgrade compatibility checks. Follow the custom code upgrade guidelines to ensure they will work as expected.
Since the Platform evolves, you will also need to upgrade your custom code:
- Identify your customization in your code so as to be able to easily find where changes may be needed on the test phase of the upgrade.
- Contributions to the extension points you defined: although we maintain compatibility between versions, you may need to check the extension point definition in the Nuxeo Platform Explorer to see if the descriptor has changed (new attributes for instance) ;
- The XHTML templates from the Nuxeo Platform you overrode to get a custom behavior: some of these templates may have changed (sometimes a lot if you plan to upgrade several versions up) and you have to identify the modifications you did before in order to apply them to the new version of these Nuxeo templates;
- The API you used in your custom Java code: some APIs were deprecated, other ones removed (like everything around jBPM).
- At server startup, check for error or warn logs that could give deprecation or upgrade information.
- For each version of the upgrade path, build your custom plugin and check if it's running correctly once deployed in the Nuxeo Platform target version. If you run into issues, you know where to search since you already identified where customizations have been done at step 1.
See Upgrade from LTS 2019 to LTS 2021 to upgrade to the LTS 2021 version of Nuxeo Platform.