X-Cart upgrade manual ===================== $Id: UPGRADE.readme,v 1.3 2003/06/03 07:47:59 svowl Exp $ I. IMPORTANT NOTES II. REQUIREMENTS III. INTRODUCTION IV. UPGRADE OVERVIEW V. BACKUP VI. PROCEDURE VII. RESTORE VIII. AFTER UPGRADE. IX. SECURITY. X. GLOSSARY. * * * * * I. IMPORTANT NOTES Before upgrading X-Cart it is highly recommended to make a backup copy of all PHP scripts, templates and create database dump. The success of the upgrade procedure depends on how your X-Cart has been customized to suit your preferences. Under some circumstances upgrade may fail. If you experience any problems with upgrading your X-Cart, we can offer you commercial manual upgrade services. If your store is alive it is highly recommended to create a test copy of your shop, perform the upgrade procedure on this copy, do a test and only then apply the upgrade to your live store. * * * * * II. REQUIREMENTS 1. Installed X-Cart version 3.2.0 or higher. 2. Installed Upgrade/Patch bundle (required for X-Cart version 3.2.0, 3.2.1, 3.2.2 only). 3. Upgrade patchset. * * * * * III. INTRODUCTION Beginning with version 3.2.0 X-Cart shopping cart software includes "Upgrade" feature. With this feature you can easily upgrade X-Cart using the so called "patchset" archive. Upgrade/patch lets you keep your own X-Cart design and avoid installation and customization steps when upgrading to a new X-Cart version. * * * * * IV. UPGRADE OVERVIEW X-Cart upgrade patchset includes files in DIFF(1) format which are used by PATCH(1) tool to change X-Cart files for supporting new version features, new files to add and the file with DIFF files checksums. The X-Cart upgrade patchset structure sample: readme.txt | newfile.php | admin/ | newfile.php | morefile.php -- new files, scripts and templates to add skin1/ | newskin.tpl | moreskin.tpl | upgrade/ 3.2.0-3.2.1/ -- shows version changing file.lst -- DIFF files listing with MD5 ckecksums INSTALL.diff | install.php.diff | admin/ -- patch DIFF files languages.php.diff | order.php.diff | * * * * * V. BACKUP The backup procedure consists of two steps. 1. Make a copy of all PHP scripts and templates. You can do it on Unix-based servers with terminal access, using the following command: tar -cvf - xcart_folder | gzip > xcart.tgz If you have FTP access only, copy xcart_folder to your backup machine using ftp client. 2. Backup database. You can do it from X-Cart administrative interface "Administration :: DB backup/Restore" using "Generate SQL file" button. * * * * * VI. PROCEDURE Upgrade procedure consists of the following steps: 1. Make sure you meet the upgrade requirements. 2. Make sure you have made a backup. 3. Uncompress upgrade archive into X-Cart folder. You can do it on Unix-based servers with terminal access, using the following commands: > cd xcart_folder > gunzip < x.x.x-x.x.x-gold_upgrade.tar.gz | tar -xvf - or > cd xcart_folder > gunzip < x.x.x-x.x.x-pro_upgrade.tar.gz | tar -xvf - depending on X-Cart version installed on your host (Gold or Pro). If you have FTP access only, uncompress the upgrade archive on your local machine (using WinRar, for example) and upload files into X- Cart folder using FTP client. 4. Open X-Cart Upgrade/Patch center. To do that log into X-Cart Administrative interface and select "Administration :: Patch/Upgrade" menu. The version of currently installed X-Cart is shown in the "Upgrade" tab. If you uncompress the upgrade archive into X-Cart upgrade folder successfully you will see the target version number ( the version number to upgrade X-Cart upto) and "Apply" button. Click "Apply" button to start upgrading X-Cart. 5. First X-Cart checks patch tool executable permissions, patch checksums and permissions on files to apply upgrade patch, this information will be shown to you on the next page. You will be prompted to enable writing permissions on files repeatedly until you do it for all files to patch. You can set write permissions on Unix-based servers with terminal access to it,by using the following command: > chmod 0666 script_file.php If you have FTP access only, set write permissions using FTP client. You should also cancel upgrade/patch procedure if upgrade patch integrity check fails. Click "Continue" to get to the following patch/upgrade step. 6. If the permissions on files are patched correctly and the patch tool is found, X-Cart starts applying the upgrade patch. After the patch has finished you will see the result in the "Applying patch" tab. Click "Finish" button to return to "Patch/Upgrade center" menu if no errors are found during the upgrade/patch procedure. Follow the "After upgrade" section of this manual. 8. If X-Cart fails to apply upgrade/patch to one or more files or apply SQL patch to the database automatically, you will see the error message(s) in red and may have to apply upgrade/patch manually. Depending on the found error(s) do one of the following: 1) If patch/upgrade failed on file(s) please see the "PATCH LOG" for details. You can apply upgrade patch manually. To do that find reject file name from "saving rejects to .." message in the patch log, open the reject file to see what happened and apply DIFF to the target file manually. See the "Upgrade overview" section for information where to get the corresponding DIFF file to patch. YOU SHOULD UNDERSTAND THE CONCEPT OF USING UNIX DIFF(1) and PATCH(1) TO PERFORM THIS OPERATION. 2) If patch/upgrade failed on database you can apply SQL upgrade patch manually. Open patch.sql file from upgrade patchset distribution and execute SQL queries through "Administration :: Patch/upgrade center :: Apply SQL patch" tab or directly on MySQL database. YOU SHOULD BE FAMILIAR WITH THE X-CART DATABASE STRUCTURE TO PERFORM THIS OPERATION. After you have applied successfully the SQL patch manually, update the X-Cart database version info using the following SQL query: > UPDATE xcart_config SET value='x.x.x' WHERE name='version' where x.x.x is an upgrade target version number, for example: value='3.2.1' 9. If you failed to apply patch/upgrade to file(s) and/or SQL database at all, you need to restore X-Cart. See the "Restore" section for details. After you have restored the X- Cart successfully follow the "Security" section. * * * * * VII. RESTORE You may need to restore your cart to original state if something goes wrong during upgrade procedure. In order to restore X-Cart follow the next steps: 1. Uncompress the saved X-Cart archive into the X-Cart folder. You can do it on Unix-based servers with terminal access, using the following commands: > gunzip < xcart.tgz | tar -xvf - 2. Restore database from the database backup. In order to do that log into X-Cart administrative interface and select "Administrative :: DB Backup/Restore" menu. If as a result of upgrade procedure cart is inoperable you can restore the database using MySQL command line utility. If you do not have access to MySQL command line utility, follow the next steps to restore X- Cart: 1) Reinstall the original X-Cart from distributive. 2) Restore the database using "Administrative :: DB Backup/Restore" menu. 3) Uncompress the saved X-Cart archive into the X-Cart folder. * * * * * VIII. AFTER UPGRADE After you have upgraded your X-Cart successfully, please check the functionality of the updated script files, templates and database by running X-Cart in both administrative and customer modes. If you experience any problems with the upgraded X-Cart you need to restore the previous version of X-Cart and X-Cart database. See the "Restore" section for details. Please read carefully all security notes in the "Security" section of this manual. * * * * * IX. SECURITY. For security reasons it is highly recommended to restore the original permissions on patched files. After you have restored the original permissions or restored X-Cart and X-Cart database from backup, remove all the files with ".php" and ".rej" extensions from the /templates_c/upgrade/ folder. These temporary files are used by the X-Cart patch/upgrade subsystem during the upgrade procedure. * * * * * X. GLOSSARY. * DIFF(1), diff file File in DIFF(1) format contains differences between two files. Diff shows differences between files line by line in any of several selectable formats. This set of differences is often called a "diff" or "patch". * PATCH(1), patch tool The tool for applying a diff file to the original. Patch will take a patch file containing any of the four forms of difference listing produced by the diff program (see DIFF(1)) and apply those differences to the original file, producing a patched version. * Upgrade/Patch bundle Upgrade/Patch bundle archive contains patch tool, patch manual page, updated PHP scripts and a template. Upgrade/Patch bundle should be installed to X-Cart versions 3.2.0, 3.2.1, 3.2.2 before applying the upgrade. * Upgrade patchset See the "Upgrade overview" section for detailed patchset description.