upgrading to the latest xarigami

Posted by: Jo on December 6, 2010  |  Last modified on Aug 12, 2012 03:28:39 PM by Jo

step by step guide to upgrading your site

Upgrading your website to the latest Xarigami is usually a smooth process with the majority of work handled by the Xarigami Upgrade script. The script can be used for any Xarigami (or Xaraya) version from 1.1.2 to the current 1.x version.  The upgrade script is responsible for upgrading your database with any new changes. However it does not upgrade your custom theme or templates. This document provides a general guide to upgrading but you should review requirements for your own site as well as the specific version upgrade needs.

  1. Check the version changes
  2. Update custom themes and templates
  3. Prepare site files for upgrade
  4. Run the upgrade script on  your site
  5. Update the website components of your site
  6. Common Upgrade Problems
  7. Specific version upgrade details

1. Check the version changes

Before you begin your upgrade, you must check for specific version changes that might affect:

  1. your theme and custom templates - there may be BL tag, block, module or other changes that require you to make changes in custom template or themes
  2. your config.system.php file - you may need to check the new version config.system.php and update your existing one accordingly with any new or changed variables
  3. other elements such as permissions, blocks or menus that might require updating on your site
  4. any new or changed modules that are required in your installation

Check the specific upgrade requirements and preparations for your upgrade. Make a list of items you need to consider for your upgrade.

It is best to test your upgrade first on a copy of your existing site. Once you have prepared all upgrade items on your list you can start on the live site.

Return to Top

2. Update custom themes and templates : IMPORTANT

There may be specific changes you need to make to your theme or custom templates for the upgrade. It is very important you upgrade your theme templates as there may be changed functionality that depends on new or changed variables or other code in templates.

If possible, make a copy of your custom theme to work on especially if there are extensive core or module template changes.  

You may know which specific system core or module templates files have changed in the new Xarigami version. If not, you should get a good diff tool (file comparison application) if you don't already have one, and diff each of your custom templates against the relevant core or module system template to see what has changed.

Update each custom template in your theme with any functional changes. Make sure you also update any javascript or other related theme files.

If possible test your adjusted theme locally or on a staging site/server prior to upgrade of your live site on a test site using a database dump from your existing live website. You can also trial an upgrade of this with the new version Xarigami and your adjusted theme.

It is very easy to upgrade to Xarigami but the custom theme templates will usually always be the biggest upgrade issue. 

Return to Top

3. Prepare site files for upgrade

A. Backup database and files, and lock site

  1. If you allow user registration on your site, lock your site to ensure users do not log in and change content during the backup period or other possible times during upgrade.
  2. Backup your existing Xarigami database!
  3. Backup your existing Xarigami files, especially your theme directory and var directory trees, and any other directories where you have custom data!
  4. Prior to adding new Xarigami version files, ensure you protect any custom content or themes from being overwritten.
  5. Your existing config.system.php must be retained so protect this. Update it as necessary for any changes in the distribution config.system.php.dist .
  6. If you have not done so already, log in to your existing Xarigami site with administration rights and ensure your site is working, prior to upgrade

B. Replace and update old files with new

  1. Replace all existing Xarigami files, directories, and modules with the new Xarigami files EXCEPT the following:
    • {var}/config.system.php
    • files below the {var} directory
    • Your custom theme(s)
    • By "replacing" we mean DELETE all old files and copy the new ones in. Do not overwrite the old files with the new ones. THIS IS IMPORTANT.
    • make sure you have also updated any non-core modules with relevant new versions
  2. Check permissions and ownership of the new files. Especially, ensure that {var}/config.system.php has appropriate permissions. For security ensure it is read only.
  3. Make sure you have cleared all your cache files in  {var}/cache/templates and {var}cache/rss
  4. If you have made adjustments to your theme or custom templates, make sure this adjusted theme is loaded in place of your existing theme (with correct id and name).

Return to Top

4. Run the upgrade.php script

  1. In the browser window where you are logged in as Administrator, point your browser to upgrade.php in your root directory and run this script. For example, http://www.mywebsite.com/upgrade.php.
  2. Read and follow the instructions in the upgrade script carefully and note any warnings.

You may find some upgrade checks are not completed. If so please run the Upgrade script database health checks and note which checks are not run successfully. You may have the option to just run the specific update to fix that check - but think carefully if they are related to custom privileges on your site.

Always run upgrade.php when you update your code, and then always run the health check again at the end of the main upgrade to ensure you have not missed any key updates to your core and modules. This is especially important if you are working on development snapshots or on monotone code.

After the upgrade script has completed, remove upgrade.php and install.php from your web directory. This is important to keep your site secure.

Return to Top

5. Update your website components and unlock site  

Your modules may need updating

  1. Go to Admin->Modules->View All. Upgrade all required modules that are showing the status of UPGRADE. Remember to Activate them after upgrade if required.
  2. Go to Blocks->View Instances and remove the Reminder block
  3. Clear your xarCacheManager output cache files if you use xarCacheManager
  4. Install any new modules you may require on your site

If you allow registered users on your site, unlock your site if you have not done so already

Check the COMMON UPGRADE PROBLEMS if you are experiencing upgrade difficulties. 

Return to Top

6. Common upgrade problems

  1. you are getting errors after upgrade, clear your template and rss cache files (and adodb if relevant). Clear your xarCacheManager output cache if you have the module installed.
  2. If you are having difficulty accessing a module, check to see if it needs upgrading, and also ensure it is activated if required
  3. If you are using a default theme, ensure it is active and also does not need upgrading
  4. The {var}/cache/rss and {var}/cache/templates directories need to be writable and executable
  5. Make sure your theme xartheme.php file has  $themeinfo['name'], $themeinfo['id']  and $themeinfo['directory'] variables. Usually directory would be the same as name, but even if it is you must ensure all variables are present

Return to Top

7. Specific version upgrade details

See specific version release information.

Related project :

xarigami core

« prev     next»

useful? share it.