Topics

Testing a Version Upgrade

Since an offline web site means lost revenue and productivity, along with additional work-hours to get it back up and running...we recommend performing a 'test installation' before upgrading a production server.

  • A 'test installation' can be performed:
    • using a subfolder of the production web site
      • This ensures an identical server environment
      • Some links and graphics may not work since they are based on either the root folder or this subfolder.  This mostly applies to any links or images embedded within HTML/WYSIWYG text
    • on a locally running 'stack' (WAMP, etc...)
      • Note: although most testing can be accomplished on any server configuration (OS, web server, php version)...in most cases you would want something very similar to the production server.  It is always best to use the same PHP major version as the production server (5.2, 5.3, 5.4, 5.5, or 5.6) without so concerned about the minor version number.
  • Before you begin the 'test installation', you should obtain the following:
    • A recent database backup file (.eql) - using the Super-Admin Tools, Database, 'Backup Database' menu item.
    • A copy of the custom theme - using the 'Export Theme' button found on the Theme Manager
      • If you do not see this button, you MUST edit the custom theme 'class.php' file and delete or change the '$stock_theme' variable to false
    • Optionally, an archive of the 'files' on the server - using the Files - 'Export Files' menu item
  • Install/Upgrade the 'test installation' to the same version/patch as the production server
    • You do not need to run the installation/upgrade until after you have extracted the 'version package' AND the most recent 'patch package' for that version.
    • Do NOT install a sample database since you'll be importing your database later.
  • Import your production server data files
    • Use the Super-Admin Tools, Database, 'Restore Database' menu item to import the .eql database backup
      • When you complete this process, you should NOT receive any message about the 'database needs to be upgraded'.  If you receive this message, your 'test installation' is a different version than your production server and you should begin again.
    • Use the Super-Admin Tools, Extensions, 'Install Extension' menu item using the 'Upload Extension' tab and checking off the 'Patch Exponent CMS or Install Theme?' to install your exported custom theme. 

    • Optionally,  use the Files - 'Import Files' menu item to install the 'files' archive to the server.

  • At this point you 'test' installation' should be identical to your production server!  You are now ready to begin your testing

  • If you are several versions behind the most recent version, you may want to try some incremental testing.  Another method would be to upgrade to the most recent version, then back-track if you encounter any issues.

  • Turn on 'Error Reporting' if it isn't already turned on.

  • Install the upgraded version/patch files to the test server and run the upgrade process.

    • In some cases the site may not look/work correctly until AFTER the upgrade process is completed.

  • If everything seems to be working, take a tour of your site and perform some routine tasks as an admin user, as a non-admin user, and as a guest user (not logged on),

  • From the Configure Website view using the Profile tab, create a new profile with the name of this site so you'll have a snapshot of the configuration for easy switching/testing in the future,  Using 'Profiles' will allow you to have a different database and custom theme for each 'site' and easily switch between them by selecting the 'test site' from the profile drop-down menu.

  • If you experience any issues, you should try:

    • Switching to one of the shipped sample themes, perhaps the one which uses the same 'theme framework' as your custom theme.  If you site works, the issue is within your custom theme.  If not, it may be an unreported issue with Exponent CMS or a database anomaly/issue.

    • If your site doesn't even work to where you can get to the interface you can try:

      • Manually changing to a shipped theme

        • Editing the /framework/conf/config.php file to change the DISPLAY_THEME_REAL line to use a shipped theme

          • define("DISPLAY_THEME_REAL",'simpletheme');

        • Delete the cache files in the following folders:

          • /tmp/views_c

          • /tmp//css

          • tmp/minify

      • Turning 'minify' off

        • Editing the /framework/conf/config.php file to change the MINIFY line to 0

        • define("MINIFY",'0');

    • If you are upgrading from a version prior to v2.2.1, you might want to conduct an incremental upgrade through v2.2.1.  This version contained a compatibility layer which will diagnose and report most theme problems caused by using obsolete calls.  See this article.  (This feature will reappear in v2.3.2 and can be activated by setting an OLD_THEME_COMPATIBLE constant to turn the compatibility back on.)
      • You must update the obsolete calls as recommended in the warning message which appear.
  • Once you are satisfied the upgraded version will work:
    • Export the custom theme from the 'test installation' if it was modified as a result of your testing.  This will be imported to the production server
    • Perform another Backup Database (.eql) operation if any time has passed, so you have a recent backup of the site.
    • Perform the upgrade of the production server

Once you've followed this process for a version upgrade or two, it becomes very easy.  The best method to stay on top of upgrades is to upgrade to them shortly after their release being mindful of any release notes.  It is sometime difficult to upgrade a very old site to a newer version which is 10 or 20 version newer than the production server.

Loading Help

Parent Help Topic

Upgrade Preparation

While seasoned Exponent CMS experts can simply dive into an 'upgrade', most users will want to make adequate preparation BEFORE beginning the upgrade procedure.

...