Nuxeo Server

Upgrading the Nuxeo Platform

Updated: April 19, 2017 Page Information Edit on GitHub

This page is scheduled for review and update. Check back soon for updated content!

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 😄

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.

Note about Redis jobs

Make sure no jobs are still queued or running before starting the upgrade procedure.

  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 Dependencies 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 Fast Track 9.1 from LTS 2016

See Upgrade from LTS 2016 to 9.1 to upgrade to Ftast Track version 9.1 of the Nuxeo Platform.

Release notes:

To LTS 2016 from LTS 2015

See Upgrade from LTS 2015 to LTS 2016 to upgrade directly to the LTS 2016 version or Upgrade from LTS 2015 following Fast Tracks to upgrade from a Fast Track version to LTS 2016.

Release notes:

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.
a month ago Solen Guitter Add links to upgrade page, hide page 'following FTs' until we release 9.2
6 months ago Solen Guitter Update links on general upgrade page
6 months ago Andrew Goodricke Add content-review-lts2016 to labels
7 months ago Kevin Leturc NXP-19481: Update MarkLogic page to detail how to configure range element indexes
10 months ago Solen Guitter 80 | dd note about Redis job
10 months ago Solen Guitter 79
a year ago Solen Guitter 78 | Fix Studio menu labels
a year ago Anahide Tchertchian 77
a year ago Solen Guitter 76
a year ago Solen Guitter 75 | NXDOC-658: Marketplace packages are now called Nuxeo Packages, add links to 7.10 release notes and upgrade notes
2 years ago Solen Guitter 74 | Replace 7.x FT by LTS 2015 version
2 years ago Solen Guitter 73
2 years ago Solen Guitter 72 | Removed mp-reset step in Upgrading Your Nuxeo Marketplace Packages section
2 years ago Manon Lumeau 71
2 years ago Antoine Taillefer 70
2 years ago Solen Guitter 69
3 years ago Manon Lumeau 68
3 years ago Solen Guitter 67 | move upgrade policy from dedicated page
3 years ago Solen Guitter 66 | Added step for manually copied JARs upgrade
3 years ago Julien Carsique 65
3 years ago Solen Guitter 64
3 years ago Solen Guitter 63 | Reorganize update steps
3 years ago Solen Guitter 62
3 years ago Solen Guitter 61 | Added section about custom code upgrade
4 years ago Solen Guitter 60 | Page formatting, added links to the 5.8 release notes and 5.7.3 upgrade notes
4 years ago Solen Guitter 59
4 years ago Julien Carsique 58
4 years ago Julien Carsique 57
4 years ago Julien Carsique 56
4 years ago Solen Guitter 55
4 years ago Julien Carsique 54
4 years ago Julien Carsique 53
4 years ago Julien Carsique 52
4 years ago Solen Guitter 50
4 years ago Solen Guitter 51
4 years ago Solen Guitter 49
4 years ago Solen Guitter 48
4 years ago Solen Guitter 47
4 years ago Solen Guitter 46
4 years ago Delphine Renevey 45
5 years ago Julien Carsique 44
5 years ago Anahide Tchertchian 43 | reference 5.7 upgrade notes
5 years ago Julien Carsique 42 | upgrade notes 5.6
5 years ago Thierry Martins 40
5 years ago Thierry Martins 41 | Migrated to Confluence 4.0
5 years ago Thierry Martins 39 | add entry to upgrade to 5.6
5 years ago Solen Guitter 38
5 years ago Solen Guitter 35
5 years ago Solen Guitter 36
5 years ago Solen Guitter 37
5 years ago stan 34
5 years ago stan 33
5 years ago Vladimir Pasquier 32
5 years ago Julien Carsique 31
6 years ago Julien Carsique 30 | workflow change was on 5.2
6 years ago Julien Carsique 29 | Add links to upgrade notes per release version
6 years ago Julien Carsique 28
6 years ago Julien Carsique 27
6 years ago Julien Carsique 26
6 years ago Julien Carsique 25
6 years ago Julien Carsique 23
6 years ago Julien Carsique 24
6 years ago Julien Carsique 22
6 years ago Julien Carsique 21
6 years ago Julien Carsique 20 | Review layout and provide details per version
6 years ago Julien Carsique 19
6 years ago Solen Guitter 18 | format
7 years ago Stéfane Fermigier 17
7 years ago Stéfane Fermigier 16
7 years ago Stéfane Fermigier 15
7 years ago Stéfane Fermigier 14
7 years ago Stéfane Fermigier 13
7 years ago Stéfane Fermigier 12
7 years ago Stéfane Fermigier 11
7 years ago Stéfane Fermigier 10
7 years ago Stéfane Fermigier 9
7 years ago Stéfane Fermigier 8
7 years ago Stéfane Fermigier 7
7 years ago Stéfane Fermigier 6
7 years ago Stéfane Fermigier 5
7 years ago Stéfane Fermigier 4
7 years ago Stéfane Fermigier 3
7 years ago Stéfane Fermigier 2
7 years ago Stéfane Fermigier 1
History: Created by Stéfane Fermigier