Home > Installation and Administration > Upgrading the Nuxeo Platform
Installation and Administration

Upgrading the Nuxeo Platform

Updated: July 17, 2023

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 5.8 to 7.10 for instance, follow 5.8 -> 6.0 -> 7.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.

Upgrade Notes

Although major changes are explicitly documented, it is recommended to look at the upgrade notes before upgrading. Upgrade notes list changes that may affect existing configuration or features after upgrade (changes on parameters, API, default behavior, etc.).

Nuxeo Upgrade Policy

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 SearchService and EventService for 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:

General Upgrade Procedure

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:

  1. Do a backup.
  2. Stop the old Nuxeo Platform.
  3. Deploy the new Nuxeo Platform version (see the Installation pages).
  4. Update the environment variable NUXEO_HOME.

  5. Update your nuxeo.conf file to make it use your custom configuration, database and data directory.

    1. Replace the old nuxeo.conf file with this new one.
  6. Upgrade your Nuxeo Packages.
  7. Upgrade and install your Studio project customization.
  8. Upgrade and install your custom code.
  9. If you have manually copied JARs in $NUXEO/nxserver/plugins or $NUXEO/nxserver/bundles (like nuxeo-platform-login-cas2 if you are using the CAS2 authentication), install the corresponding new version of the JARs.
  10. Start the new Nuxeo Platform.
  11. Check for ERROR or WARN logs in $NUXEO/log/console.log or $NUXEO/log/server.log, or Nuxeo Runtime startup errors after log Nuxeo Platform Started.

Upgrading Your Nuxeo Packages

  1. Run nuxeoctl mp-list to get the list of all downloaded and installed (started state) Nuxeo Packages.
  2. Get the list of all started Nuxeo Packages.
  3. Run nuxeoctl mp-install on each addon that was in started state at step 2.

Upgrading Your Nuxeo Studio Project

To upgrade your Nuxeo Studio project:

  1. in the Nuxeo Studio Settings, change your target platform from the Application Definition menu.
  2. 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.
  3. Install the newly tagged version of your Project on your platform by running nuxeoctl mp-install StudioProjectName-tagName.

Note

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.

Upgrading Your Custom Code

Since the Platform evolves, you will also need to upgrade your custom code:

  1. 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).
  2. At server startup, check for error or warn logs that could give deprecation or upgrade information.
  3. 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.

Detailed Upgrade by Version

To LTS 2015 from LTS 6.0 or FT 7.x

See Upgrade from 6.0 to LTS 2015

Release notes:

Upgrade notes:

To 6.0 from 5.8 or 5.9.x

6.0 release notes.

5.9.5 upgrade notes.

5.9.4 upgrade notes.

5.9.3 upgrade notes.

5.9.1 upgrade notes.

See Upgrade from 5.8 to 6.0

To 5.8 from 5.6 or 5.7.x

5.8 release notes.

5.7.3 upgrade notes.

5.7.2 upgrade notes .

5.7.1 upgrade notes.

See Upgrade from 5.6 to 5.8.

To 5.6 from 5.5

Upgrade notes.

See Upgrade from 5.5 to 5.6.

To 5.5 from 5.4.2

Upgrade notes.

See Upgrade from 5.4.2 to 5.5.

To 5.4.2 from 5.4.1

Upgrade notes.

Oracle

If using Oracle, see Upgrade to 5.4.2 with Oracle.

To 5.4.1 from 5.4.0.1

Upgrade notes.

To 5.4.0.1 from 5.4.0

Upgrade notes.

To 5.4.0 from 5.3.2

Upgrade notes.

JBoss

If using the JBoss distribution, see Upgrade to 5.4 and JBoss 5.

Workflow Feature

The workflow implementation has changed, see From the old workflow system to the new 5.4 workflow system.

To 5.3.2 from 5.3.1

Upgrade notes.

See Upgrade from 5.3.1 to 5.3.2.

MySQL

If using MySQL, see Upgrade from 5.3.1 with MySQL to 5.3.2.

To 5.3.1 from 5.3.0

Upgrade notes.

See Upgrade from 5.3.0 to 5.3.1.

To 5.3.0 from 5.2.0

Upgrade notes.

To 5.2.0 from 5.1.6

Upgrade notes.

If using JCR with PostgreSQL, see How to migrate a Nuxeo 5.1.6 to Nuxeo 5.2 under JCR+PostgreSQL configuration.

To 5.1.6 from 5.1.3

Upgrade notes.

To 5.1.3 from 5.1.2

No upgrade notes.

See Upgrade from 5.1.2 to 5.1.3.

To 5.1.x from Earlier

  1. First, stop Nuxeo EP and, before any upgrade, always backup (at least)

    • $JBOSS/server/default/lib/nuxeo*
    • $JBOSS/server/default/deploy/nuxeo.ear/
    • $JBOSS/server/default/data/
    • dump your database(s) if you have any.

  2. If you have specific configuration, back up separately the configuration files in order to easily re-apply them onto the default one (take care not to lose any modification on these files):

    • $JBOSS/server/default/deploy/[nuxeo.ear/config/](http://nuxeo.ear/config/)
    • $JBOSS/server/default/deploy/[nuxeo.ear/datasources/](http://nuxeo.ear/datasources/)
    • $JBOSS/server/default/deploy/[nuxeo.ear/platform/nuxeo-platform-search-compass-plugin*/compass.cfg.xml](http://nuxeo.ear/platform/nuxeo-platform-search-compass-plugin*/compass.cfg.xml)
    • any other JBoss files you could have changed (mail-service.xml, etc.).
  3. It could also be useful to back up logs from $JBOSS/server/default/log/.
  4. Move your JBoss directory and replace it with the one coming from the new Nuxeo EP version.
  5. Replace $JBOSS/server/default/data/ with your backup data.
  6. Apply again you configuration.
  7. Start Nuxeo.