Note on Paths

• <old-ez-root>/: The root directory where the 5.4/2014.11 installation is located in, for example: "/home/myuser/old_www/" or "/var/sites/ezp/"
  
• <new-ez-root>/: The root directory where the installation is located in, for example: "/home/myuser/new_www/" or "/var/sites/[ezplatform|ezstudio]/"

Check for requirements

• Information regarding system requirements can be found on the  Requirements documentation page; notable changes include:
  • PHP 5.5.9 or higher
  • MySQL or MariaDB 5.5 or higher
  • Browser from 2015 or newer for use with backend UI
• This page assumes you have composer installed on the machine and that it is a somewhat recent version. See Using Composer.

Upgrade steps

Step 1: Extract latest eZ Platform/Studio 16.02.x installation

The easiest way to upgrade the distribution files is to extract a clean installation of eZ Platform / eZ Studio to a separate directory.

Step 2: Move over code and config

2.1. Code

If you have code in src folder, move that over:

• <old-ez-root>/src => <new-ez-root>/src

2.2. Composer

2.2.1 Move over own packages

Assuming you have own composer packages (libraries and bundles, but not eZ Publish legacy packages), execute commands like below to add them to new install in <new-ez-root>:

composer require --no-update "vendor/package:~1.3.0"

Adapt the command with your vendor, package, version number, and add "–dev" if a given package is for dev use. Also check if there are other changes in composer.json you should move over.

2.2.2 Temporarily install XmlText Field Type

While no longer bundled, the XmlText Field Type exists and is needed to perform migration from eZ Publish's XmlText to the new docbook-based format used by RichText Field Type. From <new-ez-root> execute:

composer require --no-update --dev "ezsystems/ezplatform-xmltext-fieldtype:^1.1.0"

2.3. Config

To move over your own custom configurations, follow the conventions below and manually move the settings over:

• <old-ez-root>/ezpublish/config/parameters.yml => <new-ez-root>/app/config/parameters.yml
  • For parameters like before, for new parameters you'll be prompted on later step.
• <old-ez-root>/ezpublish/config/config.yml     => <new-ez-root>/app/config/config.yml
  • For system/framework config, and for defining global db, cache, search settings.
• <old-ez-root>/ezpublish/config/ezpublish.yml  => <new-ez-root>/app/config/ezplatform.yml
  • For site access, site groups and repository settings.

ezpublish:
    # Repositories configuration, setup default repository to support solr if enabled
    repositories:
        default:
            # For storage engine use kernel default (current LegacyStorageEngine)
            storage: ~
            # For search engine, pick the one configured in parameters.yml, either "legacy" or "solr"
            # see SolrBundle for further info: https://doc.ez.no/display/TECHDOC/Solr+Bundle
            search:
                engine: %search_engine%
                connection: default

2.4. Bundles

Move over registration of bundles you have from src and from composer packages, from old to new kernel:

• <old-ez-root>/ezpublish/EzPublishKernel.php => <new-ez-root>/app/AppKernel.php

2.5 Binary files

Binary files can simply be copied from the old to the new installation:

• <old-ez-root>/web/var[/<site_name>]/storage => <new-ez-root>/web/var[/<site_name>]/storage

2.6 Re-apply permissions and update composer

Since writable directories and files have been replaced / copied, their permissions might have changed. Re-apply permissions as explained in the installation instructions. 

When that is done, execute the following to update and install all packages from within <new-ez-root>*:

composer update --prefer-dist

2.7 Register EzSystemsEzPlatformXmlTextFieldTypeBundle

Add the following new bundle to your new kernel file, <new-ez-root>/app/AppKernel.php:

new EzSystems\EzPlatformXmlTextFieldTypeBundle\EzSystemsEzPlatformXmlTextFieldTypeBundle(), 

Step 3: Upgrade the database

3.1. Execute update SQL

Import to your database the changes provided in one of the following files, optionally read inline comments as you might not need to run some cleanup queries:

MySQL: <new-ez-root>/vendor/ezsystems/ezpublish-kernel/data/update/mysql/dbupdate-6.1.0-to-6.2.0.sql

Postgres: <new-ez-root>/vendor/ezsystems/ezpublish-kernel/data/update/postgres/dbupdate-6.1.0-to-6.2.0.sql

3.2. Execute XmlText Migration script

For migrating content from the XmlText format to the new RichText format, a migration script exists, execute the following from <new-ez-root>:

php app/console ezxmltext:convert-to-richtext -v

3.3. Migrate Page field to Landing Page (eZ Studio only)

If you have Page field (ezflow) content and an eZ Enterprise subscription, you can use a script to migrate your Page content to eZ Studio Landing Page. See Migrating legacy Page field (ezflow) to Landing Page (Enterprise) for more information.

Step 4: Re-configure web server & proxy

Varnish (optional)

If you use Varnish, the recommended Varnish (3 and 4) VCL configuration can be found in the doc/varnish folder. See also the Using Varnish page.

Web server configuration

The officially recommended virtual configuration is now shipped in the doc folder, for both apache2 (doc/apache2) and nginx (doc/nginx). Both are built to be easy to understand and use, but aren't meant as drop-in replacements for your existing configuration.

As was the case starting 5.4, one notable change is that SetEnvIf is now used to dynamically change rewrite rules depending on the Symfony environment. It is currently used for the assetic production rewrite rules.

Step 5: Link assets

Assets from the various bundles need to be made available for the webserver through the web/ document root, execute the following commands from <new-ez-root>:

php app/console assets:install --env=prod --symlink
php app/console assetic:dump --env=prod