Upgrade eZ Publish 4.1.3 to 4.2.0

Upgrading eZ Publish with eZ Flow from version 4.1.3 to 4.2.0

Preflight checklist

• Media Temple DV server - > Plesk admin -> login and verify a current full site backup is in place
• While in plesk, review var/log/error.log to check for lurking problems that may be waiting for just the worst possible time, like during an upgrade, to manifest themselves. Also be sure setting for ssh login is set to "allow".
• Copy the upgrade archive file into the httpdocs directory of the site. If many sites to upgrade, copy the upgrade file into a location where it may be subsequently copied into httpdocs directories as needed. /var/lib/psa/dumps/store is a good place to store the original. The file may then be copied from there to wherever needed. This saves a lot of time and bandwidth if upgrading more than one site per DV server. Requires login as root, if unsure, better to use up the time and bandwidth.
• Make a note of the permissions settings on existing files. The permissions should match before and after the upgrade. GENERALLY, the login user name is the owner of all the files, psacln is the default group, apache is the owner/group for /design /extension /settings and /var and 770 permissions are sufficient.
• Login to eZ Publish admin for the site, then Setup->Upgrade Check->Check File Consistency. These may be some customizations to files that will be lost in the upgrade. Save copies of these files as necessary.
• Review the official eZ Publish documentation written by Ester Heylen for this upgrade. That document is not specific to any hosting server because it cannot be. That is why I keep my own site specific documents here for the Media Temple DV servers.

Extract the download

• ssh into the httpdocs folder of the site (ssh "ftplogin-name@255.255.255.255") extract contents, and remove the archive file with the following three commands
• # gunzip ezpublish-4.2.0
• # tar -xf ezpublish-4.2.0
• # rm ezpublish-4.2.0.tar.gz

This creates a subfolder in the httpdocs named ezpublish-4.2.0. Do not worry about the permissions for now, they will be set correctly near the end of the upgrade procedure

Copy existing customizations into the newly extracted file structure

Copy settings, var, and all the custom files from the current httpdocs root into the newly extracted /ezpublish-4.2.0

• #cp -R design/ezflow_site/ ezpublish-4.2.0/design/
• #cp -R design/admin/ ezpublish-4.2.0/design/admin/
• #cp -R var/ ezpublish-4.2.0/
• #cp -Rf settings/siteaccess/ ezpublish-4.2.0/settings/ --f so no overwrite prompts
• #cp -Rf settings/override/ ezpublish-4.2.0/settings/
• #cp -R extension/ezflow/ ezpublish-4.2.0/extension/
• #cp -R extension/ezwebin/ ezpublish-4.2.0/extension/

Check the extension directory for additional custom extensions and copy them into the upgrade following the pattern of ezflow and ezwebin.

Many sites to upgrade, wrap the above commands into a shell script. Use /bin/cp in scripts to avoid overwrite prompts, because cp runs aliased on MT DV server.

Upgrade the database structure

Take the site temporarily offline using plesk control panel.

Perform database update.

mysql -u <username> -p <database> < ezpublish-4.2.0/update/database/mysql/4.2/dbupdate-4.1.0-to-4.2.0.sql

First run returned error - ERROR 1054 (42S22) at line 17: Unknown column 'user_hash' in 'ezsession'

Not sure if I missed something in an earlier upgrade or if problem with installer, ran this command at a mysql prompt to get past it:

• mysql> ALTER TABLE ezsession ADD COLUMN user_hash VARCHAR( 32 ) NOT NULL default '';

Then run the dbupdate-4.1.0-to-4.2.0.sql again and it completes without errors.

Switch into the new archive folder, regenerate the autoload arrays.

From the root of the upgrade folder /ezpublish-4.2.0/ run

# php bin/php/ezpgenerateautoloads.php --extension

If errors are generated:

• be sure the command was run from the ezpublish-4.2.0 folder
• If a "PHP Warning: fopen(): SAFE MODE Restriction in effect" error displays, set the files to be owned by the logged in user. If logged in as root, chown -R root * to make root the owner of the files and run the command again.

SSH on mediatemple allows running as root. Depending upon how the files were unpacked, they may not be owned by root. When the files are subsequently copied from the upgrade folder to httpdocs, they will be owned by root, so chown root costs nothing and is a simple way around the fopen() restriction. More on php.net

Clear caches the first time

The script per the instructions, php bin/php/ezcache.php --clear-all --purge returns with no errors. Not sure if it is permissions or what, but checking the caches, they still contain files. Manual deletion is required. **DANGEROUS COMMANDS IF RUN IN WRONG PLACE

Be sure to verify location within file structure is ezpublish-4.2.0/var/cache directory.

#rm -R -f *

And then in the ezpublish-4.2.0/var/ezflow_site/cache directory any other extension directories

#rm -R -f *

Upgrade eZ Flow.

Switch back to the upgrade folder root, httpdocs/ezpublish-4.2.0

#php bin/php/ezflowupgrade.php --url=http://packages.ez.no/ezpublish/4.2/4.2.0

My first attempt ended with an error:

Installing package 'ezflow_classes'PHP Fatal error: Call to a member function unserializeContentClassAttribute() on a non-object in /var/www/vhosts/ipliance.com/httpdocs/ezpublish-4.2.0/kernel/classes/packagehandlers/ezcontentclass/ezcontentclasspackagehandler.php on line 388

I re-enabled the site in plesk, ran the command again, and it completed without errors.

9. Regenerate the autoload array for extensions a second time to pick up new eZ Flow classes

#php bin/php/ezpgenerateautoloads.php --extension

First run it found 90 files, this run it finds 101 files.

10. Clear the caches a second time.

Because building the autoloads for the extensions throws items into /var/cache.

This seems like duplication, but if caches are not cleared prior to the ezflow upgrade, there will be problems. So yes, it must be done twice as per these directions.

Capture customizations, such as favicon, about box, page background image.

The list of these files that may be overwritten by an upgrade was built during preflight checklist, Setup->Upgrade Check->Check File Consistency

#cp design/standard/images/favicon.ico ezpublish-4.2.0/design/standard/images

#cp kernel/ezinfo/about.php ezpublish-4.2.0/kernel/ezinfo/

#cp /extension/ezflow/design/ezflow/override/templates/about.tpl ezpublish-4.2.0/extension/ezflow/design/ezflow/override/templates/about.tpl

#cp extension/ezflow/design/ezflow/images/page-bg.jpg ezpublish-4.2.0/extension/ezflow/design/ezflow/images ..to restore a custom page background

Preserve custom adserver banners..

#cp extension/ezflow/design/ezflow/override/templates/block/banner*.tpl ezpublish-4.2.0/extension/ezflow/design/ezflow/override/templates/block

Delete all current files except .htaccess and the newly created folder from the site

Turn off site in plesk admin, verify in the root of the site, httpdocs/ then ..

• # rm -Rf var/ update/ support/ share/ settings/ schemas/ packages/ lib/ kernel/ autoload/ bin/ cronjobs/ design/ doc/ extension/
• # rm -f access.php autoload.php ezpm.php ezpublish.cron index.php index_* kickstart.ini-dist pre_check.php runcronjobs.php soap.php webdav.php

Httpdocs root should now contain only .htaccess and ez_publish-4.2.0 folder, maybe a few other custom files or directories you have created. DV has some files and folders it creates by default, best to leave them.

Copy all files in the upgrade folder into the root of the httpdocs folder

• # cd ez_publish-4.2.0
• # cp -R * /<root path>/httpdocs/

Answer y to overwrite prompts for License and README files to get the latest versions of those files.

Remove the upgrade folder.

• # cd ..
• # rm -Rf ezpublish-4.2.0/

Set file permissions

Still at the httpdocs root..

• # chown -R <username> *
• # chgrp -R psacln *
• # chgrp -R apache var/ extension/ settings/ design/ autoload/
• # chmod -R 770 var/ extension/ settings/ design/ autoload/

Fix permissions on custom about box template..

• #chown <username> extension/ezflow/design/ezflow/override/templates/about.tpl
• #chgrp apache extension/ezflow/design/ezflow/override/templates/about.tpl

Re-enable the site in plesk and verify all is working

Restart your favorite browser and browse to the admin page of the site, should see the 4.2.0 version after the eZ Publish logo. While in the admin screen, clear all caches for good measure.

If Access denied pops up..

edit /settings/override/site.ini.append.php to add or alter debug settings.

[DebugSettings]
DebugOutput=enabled
..fix whatever the debug says needs fixed, then..
[DebugSettings]
DebugOutput=disabled
when everything is working.

Try a different browser or reloading the browser in admin once in a while, updates may happen on the DV server, but be cached locally making it appear problems still exist, when in fact problems are cleared.

Browse all over the site to get the caches re-built.

When satisfied site has been successfully upgraded, use Plesk to make a backup and save a snapshot of the upgraded state.

If no neat editor icons in the editor window, probably ezoe has not been enabled.

Setup->Extensions-> checkmark ezoe and click apply changes and regenerate autoload arrays.

Then should see a very ajaxified interface for editing documents. Drag and drop, cool.

Create a new plesk backup and store it in secure offsite location.

Second and final notice, backups SAVE time.