Successful Site Upgrade Strategies

Exponent is a very active project and frequently receives new features.  Issues or anomalies are also corrected shortly after being identified.  You'd think those would be great incentives to update to the most recent stable version, just to make managing and maintaining a web site much easier.  Here are some tips to help in upgrading a site, or to prepare to upgrade a site.

As a quick overview, an Exponent web site consists of five (5) components:

1. the Exponent software, which gives you an empty site and is the starting place for all sites whether being built from scratch, moved to a new server, or restored after a server failure. This is the part of the update that we provide for you.
2. the custom theme, which gives your site a unique character apart from all other web sites.  While we provide some sample themes (either in the package or additional ones on the download site), most users want to customize their own theme.  The user must maintain (update?) the custom theme and ensure it does not contain obsolete commands or calls.  It is stored/contained in the '/themes' folder.
3. the site's configuration settings, which hold the basic information about the site.  It is stored in the 'config.php' file which is created and updated by the Exponent software.  It is unique to each web server.
4. the site's content, which is the majority all you see on the web site.  This is stored in the database and is updated automatically during the 'upgrade' process.
5. the site's support files, which includes all the images used on the site, and any files made available though the site.  These are stored in the '/files' folder and are not affected by upgrades.

The first step in preparing to upgrade a site (and preventing disaster in general), is always maintain a BACK UP of your site.  In order to back up the five (5) components:

1. The Exponent software is always available on Sourceforge and through GitHub, so there's no need to keep a local copy.
2. The custom theme was created by you and in most cases you'll already maintain a copy.  However in v2.2.0+, there is a new 'Export Theme' command available in the Theme Manager to easily package and download your custom theme for restoration, or to move to a new site.  The theme may be restored/added to a site using the 'Install Extension' command.
3. The 'config.php' file is located in the '/conf' folder (v2.0/2.1) or the '/framework/conf' folder (v2.2).  The easiest way to quickly get 'back up and running' is to restore a copy of the config.php file.  For security reasons Exponent provides no automated method to retrieve nor restore the config.php file.  However, we highly recommend you use cPanel or ftp to obtain a copy.
4. The site's content (database) is easily saved or restored using the Import/Export EQL (Exponent Query Language) File commands. The export command allows you to tailor which information/tables are saved, while the import command replaces any database tables with the ones stored in the EQL file.
5. Lastly, the site's support files are easily saved using the Import/Export Files commands.

So once you have a backup of your site, especially the site's content (EQL file), you may proceed.

In a very simplistic sense, upgrading to a new version of Exponent is an easy two (2) step process.

1. Install the new software version on your server by either extracting the .zip file to the root folder/subfolder, or using 'git pull' from ssh or a shell.
2. Browse to your site and follow the instructions in the 'upgrade' notice which now appears.

That sounds so simple, what could go wrong?  Well, here are some common issues or problems which might prevent a smooth upgrade:

• Your custom theme (or a custom view) is outdated and uses obsolete commands.  Though the basic format of an Exponent theme hasn't changed much from the v0.9x days, many of the 'commands' have been updated and streamlined.  Here's the documentation on the theme template format to check/update your theme.  Here's a good article on checking for and updating themes to be v2.2.0+ compliant.  As we move into version 2.2.0+, many of the obsolete calls will no longer work.  The easiest way to confirm the problem lies in the custom theme is to switch your site to a 'shipped' theme and see if it works as expected.  If for some reason you can't log onto the site, the current theme is stored in the 'config.php' file on the line with DISPLAY_THEME_REAL.
• Your site crashed in the middle of an upgrade and now is 'broken'.  While this rarely occurs with the 'stable' software, it can exist after a test with pre-release software.  Your best bet is to run the upgrade again by manually kicking it off with a browse to your site via www.yoursite.org/install/index.php.  In many cases this will detect and correct a half-upgraded site which may also correct the issue.

While we realize that many Exponent users are actually providing a paid service to clients and their 'time is money.'  Therefore, if a site is up and running, why 'donate' your valuable time to a paying customer.  However, if YOU are the one doing most of the site content, it sure helps to have access to the 'user suggested' new features and have those annoying quirks and bugs fixed.