eZ Community » Downloads » Downloads » eZ Publish Community Project 2014.11 » Upgrading from eZ Publish Community...

Upgrading from eZ Publish Community Project 2014.07 to 2014.11

Important Information Before You Start

This is the 14th "eZ Publish 5" build, that comprises an eZ Publish 4.x build, under the 'ezpublish_legacy' folder, at the root of your eZ Publish 5 installation,
The upgrade procedure below must be applied to the latter, then the normal installation procedure for the eZ Publish 5 stack must be followed,
Make sure to follow the Virtual Host based installation procedure in the latter to initiate the setup wizard.

Upgrading from 2014.07 to 2014.11

This section describes how to upgrade your existing eZ Publish Community Project 2014.07 installation to build 2014.11. Make sure that you have a working backup of the site before you do the actual upgrade, and make sure the installation you are performing the upgrade on is offline.

Important upgrade notes:

The procedure for upgrading from eZ Publish Community Project build 2014.07 to build 2014.011 consists of the following steps:

Backing up the website
Putting the website offline (optional)
Upgrading the distribution files to 2014.11
Upgrading custom extensions
Regenerate the autoload array for extensions
Running the upgrade scripts
Updating your YAML configuration
Clearing the caches
Putting the website online (optional)

Check for requirements

It is recommended to always verify the requirements for the new version of eZ Publish before attempting an upgrade. eZ Publish Community Project 2014.11 is compatible with PHP version 5.4.4 and above. For more information regarding system requirements check out "Requirements for doing a normal installation".

Step 1: Backing up the website

Filesystem set: the extension and settings folders, plus any other folder where you have put your custom developments in (e.g. design/mydesign)
Content set: the var/storage, var/<vardir>/storage folders, and a dump of the database (nb: for ezdb cluster mode, a dump of the storage database is needed instead of the storage folders; for ezdfs cluster mode both a dump of the storage database and a backup of the shared var folder on nfs)
Optional: the complete installation directory of eZ Publish, except for the var directory and for the eZFind index directory. This is mandatory if you have customized the .htaccess or config.php files

Tip: if you have many user sessions, and the session data is stored in the database, it might be a good idea to remove all data from the session table before backing it up
Tip: in ezdb and ezdfs cluster modes, it is a good idea to clear all caches before dumping the storage database, as it is not easy to only backup storage and not caches

Step 2: Putting the website offline (optional)

This step is recommended but not mandatory

Put the public website offline and set up a courtesy page to prevent end users from accessing the website while you upgrade. This involves generally modifying the webserver configuration. Make sure you have a different vhost available to access the public website using a private IP address or hostname during the upgrade process
Disable execution of eZ Publish cronjobs

Step 3: Upgrading the distribution files (legacy)

The easiest way to upgrade the distribution files is to unpack eZ Publish 2014.11 to a separate directory and then copy into it the directories that contain site-specific files from the existing installation. Make sure that you copy the following directories:

ezpublish_legacy/design/<mydesign>
ezpublish_legacy/design/<mydesign_admin>
ezpublish_legacy/var
ezpublish_legacy/settings/siteaccess
ezpublish_legacy/settings/override

Replace "mydesign" and "mydesign_admin" with the actual names of your designs.

Important note: Because the new directory has replaced the original directory, the directory permissions need to be fixed. Use the following commands to do this.

(You have the choice between Shell commands or Alternative shell commands):

Shell commands

These shell commands will give proper permission to the web server:

cd </path/to/your/eZ/Publish/directory>
cd ezpublish_legacy
chmod -R a+rwx design extension settings var

Alternative shell commands

These commands will setup the permission more correctly, but require knowledge about the user account used for running the web server process.cd </path/to/your/eZ/Publish/directory>

cd </path/to/your/eZ/Publish/directory>
cd ezpublish_legacy
chmod -R og+rwx design extension settings var
chown -R <webuser>:<webusergroup> design extension settings var

Symfony part
If you want to re-use your composer.json and EzPublishKernel.php, follow these steps:

1. Update composer.json according to the diff. Recommendation is to apply exactly what has changed.
- Remove all zetacomponents dependencies (they're now implicit dependencies, pointing to real tags)
- Update Symfony dependencies (optional but highly recommended). This affects symfony/*, twig/extensions and sensio/*, doctrine/*.
- Add symfony/expression-language and sensio/framework-extra-bundle.
Update EzPublishKernel.php according to the diff.
Add SensioFrameworkExtraBundle, LiipImagineBundle, FOSHttpCacheBundle, EzPublishIOBundle and OneupFlysystemBundle.
Warning: order does matter!
(Optional, but recommended) Update config.yml according to the diff (same for config_dev.yml / config_prod.yml).
(Optional) Update routing.yml according to the diff.
(Optional) Varnish users: update VCL file. VCL for Varnish 4 is also available.

Step 5: Custom extensions

If you are using custom extensions, the sub-directories inside the "extension" directory will also have to be copied. However, make sure that you do not overwrite any extensions that are included in the eZ Publish 2014.07 tarball, which are currently:

Bundled and enabled

ezautosave-5.3.0
ezie-5.3.1
ezmultiupload-5.3.0
ezodf-5.3.1
ezprestapiprovider-5.3.0
eztags-1.3.0

Bundled but not enabled

ezfind-2014.11.0
ezscriptmonitor-5.3.1

Optional installation (depending on the package chosen during the installation wizard)

ezdemo-5.3.2
ezflow-5.3.3
ezgmaplocation-5.3.1
ezstarrating-5.3.1
ezwt-5.3.1
ezsi-5.3.3
ezmbpaex-5.3.2

Step 6: Regenerate the autoload array for extensions

To regenerate the autoload array, execute the following script from the root of your eZ Publish installation:

cd </path/to/your/eZ/Publish/directory>
php ezpublish/console ezpublish:legacy:script bin/php/ezpgenerateautoloads.php --extension

Step 7: Updating your YAML configuration

Please refer to these upgrade instructions: https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/bc/changes-5.4.md

Step 8: Clearing the caches

Whenever an eZ Publish website is upgraded, all caches must be cleared in a proper way. This should be done from the root directory of your eZ Publish installation:

cd </path/to/your/eZ/Publish/directory>
php ezpublish/console cache:clear
php ezpublish/console ezpublish:legacy:script bin/php/ezcache.php --clear-all --purge

Tip : Purging ensures that the caches are physically removed. When the "--purge" parameter is not specified, the caches will be expired but not removed.

Sometimes the script is unable to clear all cache files because of restrictive file/directory permission settings. Make sure that all cache files have been cleared by inspecting the contents of the various cache sub-directories within the "var" directory (typically the "ezpublish_legacy/var/cache/" and "ezpublish_legacy/var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, you need to remove them manually.

Step 9: Putting the website back online

This step is optional, and is only needed if you put the website offline at step 2

warm up the template cache by pre-compiling template files. This should be done from the root directory of your eZ Publish installation:

cd </path/to/your/eZ/Publish/directory>
php ezpublish/console ezpublish:legacy:script bin/php/eztc.php --wwwdir=<value> --index-file=<value>

re-enable the cronjobs
warm up the content cache: use a tool such as curl or wget that will navigate the website to force eZPublish to generate the HTTP and persistence cache for all content
change the webserver / firewall configuration to allow public access to your website again

Migrating the DFS cluster configuration (optional)

If your legacy setup is using eZDFSFileHandler to manage cache, images and binary files, you need to add native configuration for it on the new stack.

Database update

Update your database with the following command

UPDATE ezdfsfile SET scope='image' WHERE scope='images';

Base legacy configuration

Assuming a typical dfs configuration, in ezpublish_legacy/settings/override/file.ini.append.php, like the following.

[ClusteringSettings]
FileHandler=eZDFSFileHandler
 
[eZDFSClusteringSettings]
MountPointPath=/var/nfs
DBBackend=eZDFSFileHandlerMySQLiBackend
DBHost=clusterhost
DBPort=3306
DBName=ezpublish_cluster
DBUser=clusteruser
DBPassword=clusterpassword
MetaDataTableNameCache=ezdfsfile_cache

Cluster doctrine connection

First, if the cluster database is different from the content database (and it should), you need to create a new doctrine dbal connection.

# ezpublish/config/ezpublish.yml or ezpublish/config/config.yml
doctrine:
    dbal:
        connections:
            cluster:
                driver: pdo_mysql
                host: clusterhost
                port: 3306
                dbname: ezpublish_cluster
                user: clusteruser
                password: clusterpassword
                charset: UTF8

This connection will be made available as doctrine.dbal.cluster_connection.

Metadata handler configuration

Handing of file metadata in the ezdfs tables is handled by an IO metadata handler. You need to declare a new one that uses the doctrine connection created above.

ez_io:
    metadata_handlers:
        dfs:
            legacy_dfs_cluster:
                connection: doctrine.dbal.cluster_connection

“dfs” is the name of our custom metadata handler, and “legacy_dfs_cluster” its type.

Flysystem adapter

In order to read and write files to the NFS mount point (/var/nfs), you need to add a flysystem adapter. One important note is that the var directory and to storage directory will not be added when writing files, meaning that we need to specify them in the configuration.

oneup_flysystem:
    adapters:
        nfs_adapter:
            local:
                directory: "/var/nfs/$var_dir$/$storage_dir$"

$var_dir$ and $storage_dir$ will be replaced by the matching configuration values, and should be used as is for legacy compatibility. The value of “directory” will be set depending on the configuration, for instance to “/var/nfs/var/ezdemo_site/storage”.

DFS binary data handler

The next step is to configure a binary data handler that uses the flysystem adapter we created above. It is very similar to what was done for the metadata one:

ez_io:
    binarydata_handlers:
        nfs:
            flysystem:
                adapter: nfs_adapter

Final step: configuring the metadata and binarydata handlers

The last thing to do is set eZ Publish to use the binarydata and metadata handlers we created above, in the siteaccess aware configuration:

ezpublish:
    system:
        default:
            io:
                metadata_handler: dfs
                binarydata_handler: nfs

Post-final step: update the cluster rewrite rules

The existing rewrite rule for images must be changed, as they can now be handled by the new stack.
Edit this rewrite rule:

 RewriteRule ^/var/([^/]+/)?storage/images(-versioned)?/.* /index_cluster.php [L]

So that it rewrites to index.php instead:

 RewriteRule ^/var/([^/]+/)?storage/images(-versioned)?/.* /index.php [L]