Installation and Administration

Upgrade from 6.0 to LTS 2015

Updated: July 17, 2023

For the general upgrade process, see the How to Upgrade Nuxeo page.

This chapter highlights some major information about upgrade from Nuxeo Platform 6.0 LTS to Nuxeo Platform LTS 2015 (7.10). We strongly encourage you to also have a quick read of the detailed list of upgrade notes for each Fast Track version.

Installation & Configuration

JDK Upgrade

JDK 1.8 update 40 (8u40) is required.

Elasticsearch Upgrade

Upgrading Elasticsearch to the latest 1.5.x is not mandatory but advised (1.1.x is still supported).

Elasticsearch for Audit Logs

We chose to use Elasticsearch for audit logs as of Nuxeo 7.3: this improves scalability especially when using Nuxeo Drive with a large set of users.

Elasticsearch for audit logs is set as the default back-end for new install but not for upgrades. If you choose to enable it, it is an important change that implies to:

  1. Activate Elasticsearch for audit logs:

    nuxeoctl config audit.elasticsearch.enabled true
    
  2. Migrate data from the SQL database to an Elasticsearch index:

    nuxeoctl config audit.elasticsearch.migration true
    

    This launches a background job at server startup to migrate data from the nxp_logs, nxp_logs_extinfo and nxp_logs_mapextinfo tables of the SQL database to the ${audit.elasticsearch.indexName} Elasticsearch index.

    Note: Migration uses batch processing. The number of log entries processed per batch can be configured by audit.elasticsearch.migration.batchSize property. Default value is 1000. As an example, we successfully tested migration of 22,000,000 log entries with an average speed of 1,500 entries / second using audit.elasticsearch.migration.batchSize=10000 on a Linux virtual machine with two cores, 4 GB RAM, a local PostgreSQL instance and an embedded Elasticsearch instance.

  3. Once the migration is done:

    nuxeoctl config audit.elasticsearch.migration false
    

Take into account the audit related Elasticsearch indexes when backing up / restoring a Nuxeo instance, so make sure you read the Backing Up and Restoring the Audit Elasticsearch Index section.

Related Configuration Parameters

ParameterDefault valueDescription
audit.elasticsearch.enabled false | true Since Nuxeo 7.3. See Disabling Elasticsearch for Audit Logs Defaults to false on server upgrade, true on new install.
audit.elasticsearch.migrationfalseSee Triggering SQL to Elasticsearch Audit Logs Migration
audit.elasticsearch.migration.batchSize1000See Triggering SQL to Elasticsearch Audit Logs Migration
audit.elasticsearch.indexName${elasticsearch.indexName}-auditSee Configuring Nuxeo to Access the Cluster

ACL Factorization

Only available for PostgreSQL, the ACLR should be factorized as "Everyone". Rebuild the ACLR table with nx_rebuild_read_acls stored procedure:

SELECT nx_rebuild_read_acls();

Cluster

Quartz Upgrade

Quartz library has been upgraded from 1.8.6 to 2.2.2. Therefore the table structure has changed and you need to run a migration script as explained in the Quartz 1.8.x to Quartz 2.0 Migration Guide, paragraph "Making Changes For Setups Using JDBCJobStore".

Run the script to upgrade Quartz tables from 1.8.6 to 2.2.2 (also available in your Nuxeo distribution):

$ psql -U <nuxeo_user> <nuxeo_db> -f $NUXEO_HOME/bin/upgrade-6.0-7.10/7.3-quartz-1.8.6-2.2.2.sql   

Node ID

With clustering enabled, it is now highly recommended to set an explicit unique node id on each cluster node:

nuxeoctl config repository.clustering.id 12345

The id can be a string on Oracle, but must be an integer on other databases.

The cluster node id should be defined explicitly because this way it's stable, known to the server administrator, and has no risk of collision with another randomly-generated one.

Note that if a cluster node crashes, cleaning the cluster_nodes and cluster_invals tables must be done manually by a DBA as Nuxeo has no way of knowing what nodes are currently connected or not and which should be cleaned.

See NXP-17180 for details.

Notification Subscriptions Upgrade

Notification subscriptions have to be migrated using the migrate_notifications.sql script, only available for PostgreSQL and Oracle databases.

Run the script file to migrate notification subscriptions (PostgreSQL, Oracle) (also available in your Nuxeo distribution):

Postgresql
$ psql -U <nuxeo_user> <nuxeo_db> -f $NUXEO_HOME/bin/upgrade-6.0-7.10/notification-subscriptions-migration.psql.sql   

See: NXP-16704.

Oracle
$ sqlplus <nuxeo_user>/<nuxeo_password> @$NUXEO_HOME/bin/upgrade-6.0-7.10/notification-subscriptions-migration.oracle.sql

Blob Management

Repository config must define a default blob provider. If you define your own default-repository-config, you must align it on default-repository-config.xml.nxftl

  <extension target="org.nuxeo.ecm.core.blob.BlobManager" point="configuration">

    <blobprovider name="default">

      <class>${nuxeo.core.binarymanager}</class>

      <property name="path">${repository.binary.store}</property>

      <property name="key">${nuxeo.core.binarymanager_key}</property>

    </blobprovider>

  </extension>

New Configuration Parameters

ParameterDefault valueDescription
org.nuxeo.cmis.enableComplexPropertiesfalseWhen true, complex properties are exposed as JSON-encoded strings.
nuxeo.lock.managerredisIf Redis is used, lock management is done through it.
org.nuxeo.cmis.elasticsearchfalseTo send the CMISQL queries to Elasticsearch, set to true.
nuxeo.server.tomcat_admin.host localhost Tomcat server's "admin" host. This is the address on which the server waits for a shutdown command.
nuxeo.virtual.host This parameter can be used to replace the nuxeo-virtual-host request header (usually when using HTTPS) when it is not possible to set it at the reverse-proxy level. The use of the header is still preferred as the parameter forces your Nuxeo instance to be accessible from one URL only. Example: https://my.nuxeo.com/
seqgen.elasticsearch.indexName${elasticsearch.indexName}-uidgen See Configuring Nuxeo to Access the Cluster

Data Migration

You must update the size of the column DATA in table CONTENT, which has changed in Nuxeo Platform LTS 2015, from 40 to 250. For instance for PostgreSQL:

  • In Nuxeo Platform 6.0:

    data character varying(40)
    
  • In Nuxeo Platform LTS 2015:

    data character varying(250)
    

Code Migration

New Configuration Service

A new runtime configuration service is available to ease up documenting and overriding miscellaneous application properties.

The following error will appear at startup if your server nuxeo.conf file still references properties that have been moved to this service. A typical error will look like:

ERROR [OSGiRuntimeService] Nuxeo Platform Started
======================================================================
= Component Loading Errors:
  * Property 'nuxeo.jsf.useAjaxTabs' should now be contributed to extension point 'org.nuxeo.runtime.ConfigurationService', using target 'configuration'

To fix this error:

  1. Remove the property from nuxeo.conf.
  2. Add an XML contribution to org.nuxeo.runtime.ConfigurationService#configuration.

    Sample XML contribution to configure nuxeo.jsf.useAjaxTabs

    <?xml version="1.0"?>
    <component name="org.nuxeo.ecm.platform.ajaxified.tabs.config">
      <!-- require the original component declaring the property -->
      <require>org.nuxeo.ecm.platform.ui.web.configuration.default</require>
      <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">
        <property name="nuxeo.jsf.useAjaxTabs">true</property>
      </extension>
    </component>
    

Example of properties which have been migrated to ConfigurationService:

ParameterDefault valueDescription
nuxeo.automation.properties.value.trimtrueThe Properties in automation, are of the form key=myvalue. This property allows trimming of spaces around the value. For example key = myvalue, would result in the value being "myvalue" or " myvalue" (note the space at the beginning of the value), depending on this configuration.

New Batch Upload API

The batch upload API has changed to be exposed as a REST resource endpoint. The old API using /site/automation/batch/upload is deprecated but kept for backward compatibility.

For security reasons, the old API does not allow to use a client-side generated batch id passed as a request header, see NXP-18030 for details.Therefore it is strongly recommended to upgrade to the new batch upload API.

If this is not possible for any reason and you absolutely need to keep using the old API you have two options:

  • Not passing the X-Batch-Id header. The batch id will then be automatically generated server-side.
  • Setting the allowClientGeneratedBatchId configuration property to true (not recommended).

Removal of the IPTC Schema

Most IPTC metadata have been removed. Only legend, source and copyright have been kept and are mapped to fields dc:description, dc:source and dc:rights.

See the page Binary Metadata for more information.

Migrating Theme and Web Resources

Please refer to the dedicated documentation at Theme Upgrade to LTS 2015.

Migrating Inline JavaScript Declarations

When migrating from 7.4 to 7.10, a new mechanism to defer loading of JavaScript resources might break inline JavaScript declarations: most of JavaScript resources will be loaded at the end of the page body to optimize page rendering (except a few libraries like jQuery,JSF and RichFaces).

If you get an error when loading JavaScript resources, the original template should be modified to rely on the h:outputScript tag instead a simple script HTML tag, and to use a variable available to all default pages for resource re-targeting. Here is a sample migration:

HTML5 Drag and Drop Customization

Some deprecated parameters have been removed in 7.10. Therefore you have to update the link defined for the Chain.FileManager.ImportWithMetaDataInSeam action:

  1. Replace the layout parameter by layouts.
  2. Replace the schema parameter by schemas.

See the page How to Customize the HTML5 Drag and Drop Import with Metadata Form.

End of Life Nuxeo Packages

The following Nuxeo Packages are no longer released:

  • Automated Document Categorization
  • Nuxeo - BIRT Integration
  • Faceted search
  • Nuxeo DAM PDF Export
  • Nuxeo DAMCompat
  • Nuxeo OpenSocial
  • Nuxeo Poll
  • Nuxeo RSS Reader
  • Nuxeo Shared Bookmarks
  • Nuxeo Sites and Blogs
  • Nuxeo Social Collaboration
  • Nuxeo Web Mobile (SC)

Live Edit

Live Edit is no longer maintained. For office document offline editing, Nuxeo Drive provides a Direct Edit feature that enables users to edit files stored in the Nuxeo Platform using their native application.

7.x Upgrade and Release Notes

Upgrade notes:

Release notes: