Permalink
Fetching contributors…
Cannot retrieve contributors at this time
686 lines (583 sloc) 28 KB
title review labels toc confluence tree_item_index version_override history
Upgrading the Nuxeo Platform
comment date status
2017-12-11
ok
content-review-lts2016
upgrade
akervern
lts2017-ok
true
ajs-parent-page-id ajs-parent-page-title ajs-space-key ajs-space-name canonical canonical_source page_id shortlink shortlink_source source_link
31033314
Nuxeo Server
NXDOC
Nuxeo Platform Developer Documentation
Upgrading+the+Nuxeo+Platform
3343538
sgQz
/display/NXDOC/Upgrading+the+Nuxeo+Platform
800
LTS 2015 6.0
710/admindoc/upgrading-the-nuxeo-platform
60/admindoc/upgrading-the-nuxeo-platform
author date message version
Solen Guitter
2016-08-05 13:24
dd note about Redis job
80
author date message version
Solen Guitter
2016-07-25 08:55
79
author date message version
Solen Guitter
2016-04-15 10:05
Fix Studio menu labels
78
author date message version
Anahide Tchertchian
2015-12-14 15:52
77
author date message version
Solen Guitter
2015-11-26 16:04
76
author date message version
Solen Guitter
2015-11-26 16:03
NXDOC-658: Marketplace packages are now called Nuxeo Packages, add links to 7.10 release notes and upgrade notes
75
author date message version
Solen Guitter
2015-11-12 10:26
Replace 7.x FT by LTS 2015 version
74
author date message version
Solen Guitter
2015-10-02 14:57
73
author date message version
Solen Guitter
2015-07-02 16:05
Removed mp-reset step in Upgrading Your Nuxeo Marketplace Packages section
72
author date message version
Manon Lumeau
2015-06-30 15:17
71
author date message version
Antoine Taillefer
2015-06-30 14:24
70
author date message version
Solen Guitter
2014-11-26 17:47
69
author date message version
Manon Lumeau
2014-11-18 10:27
68
author date message version
Solen Guitter
2014-08-21 15:05
move upgrade policy from dedicated page
67
author date message version
Solen Guitter
2014-08-21 14:47
Added step for manually copied JARs upgrade
66
author date message version
Julien Carsique
2014-08-08 17:19
65
author date message version
Solen Guitter
2014-07-23 18:40
64
author date message version
Solen Guitter
2014-07-23 18:18
Reorganize update steps
63
author date message version
Solen Guitter
2014-07-23 11:59
62
author date message version
Solen Guitter
2014-01-21 14:02
Added section about custom code upgrade
61
author date message version
Solen Guitter
2013-11-07 14:48
Page formatting, added links to the 5.8 release notes and 5.7.3 upgrade notes
60
author date message version
Solen Guitter
2013-10-14 17:30
59
author date message version
Julien Carsique
2013-08-12 12:29
58
author date message version
Julien Carsique
2013-08-12 12:21
57
author date message version
Julien Carsique
2013-08-06 17:32
56
author date message version
Solen Guitter
2013-07-02 13:49
55
author date message version
Julien Carsique
2013-07-02 12:31
54
author date message version
Julien Carsique
2013-07-02 12:30
53
author date message version
Julien Carsique
2013-07-02 12:27
52
author date message version
Solen Guitter
2013-07-02 12:14
51
author date message version
Solen Guitter
2013-07-02 12:14
50
author date message version
Solen Guitter
2013-07-02 11:05
49
author date message version
Solen Guitter
2013-07-02 10:54
48
author date message version
Solen Guitter
2013-07-02 10:51
47
author date message version
Solen Guitter
2013-07-02 10:22
46
author date message version
Delphine Renevey
2013-06-13 18:35
45
author date message version
Julien Carsique
2012-10-29 18:16
44
author date message version
Anahide Tchertchian
2012-10-29 17:52
reference 5.7 upgrade notes
43
author date message version
Julien Carsique
2012-10-16 16:42
upgrade notes 5.6
42
author date message version
Thierry Martins
2012-09-04 10:46
Migrated to Confluence 4.0
41
author date message version
Thierry Martins
2012-09-04 10:46
40
author date message version
Thierry Martins
2012-09-03 14:10
add entry to upgrade to 5.6
39
author date message version
Solen Guitter
2012-05-22 17:40
38
author date message version
Solen Guitter
2012-05-22 17:39
37
author date message version
Solen Guitter
2012-05-22 17:39
36
author date message version
Solen Guitter
2012-05-22 17:39
35
author date message version
stan
2012-05-03 19:19
34
author date message version
stan
2012-05-03 19:00
33
author date message version
Vladimir Pasquier
2011-12-16 16:04
32
author date message version
Julien Carsique
2011-12-14 12:39
31
author date message version
Julien Carsique
2011-07-19 17:08
workflow change was on 5.2
30
author date message version
Julien Carsique
2011-06-16 19:00
Add links to upgrade notes per release version
29
author date message version
Julien Carsique
2011-06-16 17:08
28
author date message version
Julien Carsique
2011-06-16 17:07
27
author date message version
Julien Carsique
2011-06-15 14:23
26
author date message version
Julien Carsique
2011-06-15 14:01
25
author date message version
Julien Carsique
2011-06-15 14:00
24
author date message version
Julien Carsique
2011-06-15 14:00
23
author date message version
Julien Carsique
2011-06-15 13:59
22
author date message version
Julien Carsique
2011-06-15 12:26
21
author date message version
Julien Carsique
2011-06-15 12:25
Review layout and provide details per version
20
author date message version
Julien Carsique
2011-06-15 11:07
19
author date message version
Solen Guitter
2011-03-16 16:01
format
18
author date message version
Stéfane Fermigier
2010-07-22 14:43
17
author date message version
Stéfane Fermigier
2010-07-22 10:27
16
author date message version
Stéfane Fermigier
2010-07-22 10:24
15
author date message version
Stéfane Fermigier
2010-07-22 10:14
14
author date message version
Stéfane Fermigier
2010-07-22 09:14
13
author date message version
Stéfane Fermigier
2010-07-22 09:10
12
author date message version
Stéfane Fermigier
2010-07-22 08:55
11
author date message version
Stéfane Fermigier
2010-07-22 08:51
10
author date message version
Stéfane Fermigier
2010-07-21 20:11
9
author date message version
Stéfane Fermigier
2010-07-21 20:05
8
author date message version
Stéfane Fermigier
2010-07-21 19:21
7
author date message version
Stéfane Fermigier
2010-07-21 19:01
6
author date message version
Stéfane Fermigier
2010-07-21 18:39
5
author date message version
Stéfane Fermigier
2010-07-21 18:23
4
author date message version
Stéfane Fermigier
2010-07-21 18:18
3
author date message version
Stéfane Fermigier
2010-07-21 18:12
2
author date message version
Stéfane Fermigier
2010-07-21 18:00
1

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.

{{#> callout type='note' heading='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.).

{{/callout}}

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]({{page page='setup-best-practices'}}) (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.

{{#> callout type='note' heading='Note about Redis jobs '}}

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

{{/callout}}

  1. Do a [backup.]({{page page='backup-and-restore'}})

  2. Stop the old Nuxeo Platform.

  3. Deploy the new Nuxeo Platform version (see the [Installation]({{page page='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.

    • Report your custom configuration (uncommented lines in the old Nuxeo Platform nuxeo.conf) into the nuxeo.conf file of the target Nuxeo Platform version.

      {{#> callout type='warning' }}

      Be 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]({{page page='elasticsearch-setup#disablingelasticsearchforauditlogs'}})
      • audit.elasticsearch.migration: [Triggering SQL to Elasticsearch Audit Logs Migration]({{page page='elasticsearch-setup#triggeringsqltoelasticsearchauditlogsmigration'}}){{/callout}}
    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.

{{> anchor 'marketplace-packages-upgrade'}}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.

{{> anchor 'studio-project-upgrade'}}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.

{{> anchor 'custom-code-upgrade'}}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 10.1 from LTS 2017

See [Upgrade from LTS 2017 to 10.1]({{page version='' space='' page='upgrade-from-lts-2017-to-10.1'}}) to upgrade to the latest Fast Track of Nuxeo Platform.

Release Notes:

  • [10.x Release notes]({{page version='' space='' page='nuxeo-server-release-notes'}})

To LTS 2017 from LTS 2016

See [Upgrade from LTS 2016 to LTS 2017]({{page version='' space='nxdoc' page='upgrade-from-lts-2016-to-LTS-2017'}}) to upgrade to the LTS 2017 version or [Upgrade from LTS 2016 following Fast Tracks]({{page version='' space='' page='upgrade-from-lts-2016-following-fast-tracks'}}) to upgrade from a Fast Track version to LTS 2017.

Release notes:

  • [9.x Release notes]({{page version='910' space='nxdoc' page='nuxeo-server-release-notes'}})

To LTS 2016 from LTS 2015

See [Upgrade from LTS 2015 to LTS 2016]({{page page='upgrade-from-lts-2015-to-lts-2016'}}) to upgrade directly to the LTS 2016 version or [Upgrade from LTS 2015 following Fast Tracks]({{page page='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]({{page page='upgrade-from-60-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.](https://jira.nuxeo.com/browse/NXP-14884?jql=project%20%3D%20%22NXP%22%20AND%20resolution%20%3D%20Fixed%20AND%20fixVersion%20%3D%20%225.9.5%22%20AND%20(%22Impact%20type%22%20%3D%20%22API%20change%22%20OR%20%22Upgrade%20notes%22%20is%20not%20EMPTY)

[5.9.4 upgrade notes.](https://jira.nuxeo.com/browse/NXP-14478?jql=project%20%3D%20%22NXP%22%20AND%20resolution%20%3D%20Fixed%20AND%20fixVersion%20%3D%20%225.9.4%22%20AND%20(%22Impact%20type%22%20%3D%20%22API%20change%22%20OR%20%22Upgrade%20notes%22%20is%20not%20EMPTY)

[5.9.3 upgrade notes.](https://jira.nuxeo.com/browse/NXP-13877?jql=project%20%3D%20%22NXP%22%20AND%20resolution%20%3D%20Fixed%20AND%20fixVersion%20%3D%20%225.9.3%22%20AND%20(%22Impact%20type%22%20%3D%20%22API%20change%22%20OR%20%22Upgrade%20notes%22%20is%20not%20EMPTY)

[5.9.1 upgrade notes.](https://jira.nuxeo.com/browse/NXP-13268?jql=project%20%3D%20%22NXP%22%20AND%20resolution%20%3D%20Fixed%20AND%20fixVersion%20%3D%20%225.9.1%22%20AND%20(%22Impact%20type%22%20%3D%20%22API%20change%22%20OR%20%22Upgrade%20notes%22%20is%20not%20EMPTY)

See [Upgrade from 5.8 to 6.0]({{page page='upgrade-from-58-to-60'}})

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]({{page page='upgrade-from-56-to-58'}}).

To 5.6 from 5.5

Upgrade notes.

See [Upgrade from 5.5 to 5.6]({{page page='upgrade-from-55-to-56'}}).

To 5.5 from 5.4.2

Upgrade notes.

See [Upgrade from 5.4.2 to 5.5]({{page page='upgrade-from-542-to-55'}}).

To 5.4.2 from 5.4.1

Upgrade notes.

Oracle

If using Oracle, see [Upgrade to 5.4.2 with Oracle.]({{page page='upgrade-from-541-to-542-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]({{page page='from-the-old-workflow-system-to-the-new-54-workflow-system'}}).

To 5.3.2 from 5.3.1

Upgrade notes.

See [Upgrade from 5.3.1 to 5.3.2]({{page page='upgrade-from-531-to-532'}}).

MySQL

If using MySQL, see [Upgrade from 5.3.1 with MySQL to 5.3.2]({{page page='upgrade-from-531-with-mysql-to-532'}}).

To 5.3.1 from 5.3.0

Upgrade notes.

See [Upgrade from 5.3.0 to 5.3.1]({{page page='upgrade-from-530-to-531'}}).

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]({{page page='upgrade-from-516-with-jcr-postgresql-to-520'}}).

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]({{page page='upgrade-from-512-to-513'}}).

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.