Upgrading customer sites #

This page is for system administrators and support managers at a host who keep many Exponential installations on current releases. It answers: how to find which release each site runs, how to plan upgrades across customers, which steps an upgrade within the 6.0 line takes, how to check the result, and how to recover when a step fails.

The procedure is the installation book's chapter 11, Upgrading and the guide Upgrading; this page arranges it for a host. Customers coming from older major versions or other products are on Migrating customers.

Contents #

1. Rules before anything else
2. Take inventory
3. Plan the upgrade per customer
4. The upgrade within the 6.0 line
5. Check the result
6. When something goes wrong
7. Checklist

Rules before anything else #

• Never run an installer over an existing site. The setup wizard, the kickstarter and exp:install create a new database. "An upgrade replaces the code and updates the existing database in place." exp:install refuses to run where an installation exists; "Do not add --force to get past either on a live site" (11.1).
• Back up first, every time. "The database step is the one that cannot be undone by putting files back."
• Run as the site's user. Files created by root in var/ break the site later.
• A published release cannot be changed. "The way to get a fix is the next version." Plan to move forward, not to patch a release in place.

Take inventory #

For each installation, record the release, the PHP version, the database engine and the web server or engine:

• In the administration: Setup > System information names the version, PHP and the server that answered.

• On the command line: ./console exp:systeminfo --json.

• In the database, the version row (its name keeps the historic spelling on purpose):

  mysql -u USER -p DATABASE -e "SELECT name, value FROM ezsite_data WHERE name LIKE 'ezpublish-%';"

  Use the equivalent client for PostgreSQL or SQLite.

Which part of the guide applies follows from the version (Which part do I read?):

Plan the upgrade per customer #

The upgrade within the 6.0 line #

From 11.6 From any 6.0.x to today and Part C:

1. Maintenance on and a fresh backup:

   php bin/php/maintenance.php on --message="Upgrade in progress" --until=30m

2. Put the new code in place: a checkout of the new tag, or composer update of se7enxweb/exponential in the project's composer.json. Keep settings/override/, settings/siteaccess/, your extensions and designs out of any command that replaces files. Then:

   php bin/php/ezpgenerateautoloads.php -e
   php bin/php/ezcache.php --clear-all --allow-root-user

3. Apply the database update of the line, once, whole, in order: update/database/<engine>/6.0/dbupdate-6.0.0-6.0.15.sql. Files exist for MySQL (used for MariaDB too), PostgreSQL and SQLite; Oracle's files come with the ezoracle extension, and MongoDB needs no SQL file (11.3 By engine).

   mysql -u USER -p DATABASE < update/database/mysql/6.0/dbupdate-6.0.0-6.0.15.sql

4. Run the data scripts of the line once (once per var directory, on every web server of a cluster):

   php update/common/scripts/6.0/createaudittables.php
   php update/common/scripts/6.0/movetrashrecords.php --remove-file

5. Unique logins. List accounts that share a login, and add the unique index when there are none:

   ./console exp:user-login-check --allow-root-user
   ./console exp:user-login-check --fix-index --allow-root-user

6. Read the checklist of every period you pass (changelogs and behavior-change notes, listed in C3). The changes people meet most: accounts without an ezuser_setting row cannot sign in; overrides follow Priority; security headers, cookie flags and a stricter upload check are on by default.

7. Check own extensions: ./console exp:checkclasses --allow-root-user reports classes PHP refuses to load.

8. Deploy: reload the PHP-FPM that serves the site, or run ./console exp:velocity deploy on Velocity (Deploying changes). Clear the content cache and Velocity's response cache after the reload.

9. Maintenance off after the checks below.

Check the result #

php bin/php/ezcache.php --clear-all --allow-root-user     # ends without an error
./console exp:checkdbfiles --allow-root-user               # no file marked missing for your line

Then in the browser: the front page loads; sign in to the administration; Setup > System information shows the new version; publish a test item and see it on the site. Setup > Upgrade check and Check file consistency list files of the code that differ from the release; files changed on purpose are expected there (The upgrade check).

When something goes wrong #

Source: If something goes wrong.

Checklist #

• To do: Inventory: release, PHP, database engine and server recorded per site.
• To do: Customized sites tested on a staging copy restored from a backup.
• To do: Backup taken right before the window; restore time known.
• To do: Code, autoloads, caches, database file, data scripts and login check done in order.
• To do: The checklists of every period passed have been read.
• To do: PHP-FPM reloaded or Velocity deployed; content and response caches cleared afterwards.
• To do: exp:checkdbfiles, the upgrade check and a test publish pass; the customer is told.

Related pages #

• PHP upgrade (runbook)
• From older Exponential versions
• Automated updates with ezupdate
• Maintenance mode, Deploying changes
• Chapter 11: Upgrading
• Migrations on hosted sites, Migrations
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.