Automatic Updates
The matrix_upgrade.php script automatically upgrades your system from one version to another, displaying a file comparison of your current system and the Matrix version you are upgrading too, as well as a description of the upgrade steps that will be performed. Please note that this script only supports updates of Matrix versions 3.28.0 and higher.
Automatic updates are only available to users who have an update subscription. These subscriptions are free for personal users. For more information on how to acquire a subscription, refer to the Squiz Matrix web site.
Tip: Visit http://downloads.squiz.net/matrix-automatic-upgrades to download the automatic upgrade script. Have your username and password ready; these will have been provided to you upon approval of your update subscription application.
Bookmarks to the headings on this page:
Downloading the Matrix Upgrade Script
The Matrix Automatic Upgrades directory lists the upgrade script files available for download, as shown in the figure below.
Matrix Automatic Upgrades
These files use the file name automatic_upgrades_x-x-x.zip, where x-x-x is the version of Squiz Matrix the script supports upgrades to. For example, in the figure above, the automatic_upgrade_4-0-1.zip file can update a Squiz Matrix system to any version up to 4.0.1. It is recommended that you always use the latest version of the Matrix upgrade script available for download.
Once you have downloaded the Matrix upgrade script, unzip the file to a location on your server.
Configuring the main.conf File
Before using the Matrix upgrade script, you must first check the configuration of the main.conf, located at automatic_upgrades/conf/main.conf. The following settings must be checked:
-
CVS: the settings for the Matrix CVS server, including the server type, location and user account to connect to the server. This server is used when sourcing code from the Matrix CVS repository. By default, the following settings are used to access the public CVS repository:
- type: pserver
- server: public-cvs.squiz.net
- user: anonymous
- pre_uploaded (base_folder): the directory used when sourcing code from a pre-uploaded folder location on your server. If you are only using a CVS repository, this can be left empty.
-
file_perms: the username and group of the Apache web server. These will be used to set file system permissions after each upgrade. By default, the following settings are used:
- user: apache
- group: apache
-
cvs_skip_packages: the packages to be skipped when checking out new code from CVS. This option is useful when your system contains custom packages that you want preserved in the updated system.
An example usage of this option is as follows:'cvs_skip_packages' => Array(
'example_package_name1',
'example_package_name2',
), -
php_path, php_options: the full path to PHP to run scripts, installation steps etc. on the upgrade procedure. Command line options can be specified. For more information on the PHP options available, refer to the PHP: Options
manual.
An example usage of this option is as follows:'php_path' => '/usr/bin/php',
'php_options' => '-c /path/to/php.ini',Please note that these settings are optional. If no PHP path is specified, the system's default PHP will be used.
Understanding the Script Parameters
The Matrix upgrade script takes the system root and the version of Squiz Matrix that you want to update to as arguments. This script can also be passed the following optional arguments:
- -F: forces the copying of new system code (from CVS or a pre-upload location) even if there are modified files on the system. If omitted, the upgrade procedure will be aborted if modified files are reported.
- -n: setting this option will mean that the script will not actually perform an upgrade of your system, but instead show an upgrade report with the steps that will be performed.
- --backup=<option>: suppresses the option to backup the current system before upgrading. Setting <option> to force will perform a backup before each version upgrade, when running the script. Setting <option> to skip will mean that the script will not backup your system. If this argument is not used, users will be prompted of whether to create a backup or not.
- --cvs=<option>: set <option> to disable to temporarily disable sourcing code from the Matrix CVS repository.
- --disable-colour: disables colour.
- --pre-upload=<option>: set <option> to disable to temporarily disable sourcing code from pre-uploaded folder locations.
- --step: allows you to confirm the details of each individual installation step before continuing (e.g. 'press any key' to continue).
- --autostep: allows you to skip the confirmation prompts when proceeding between version upgrades.
- --verbose: displays a full list of upgrade steps for each version at commencement.
- --check-dif=<option>: creates a comparison between the current system and the version being updated to. Setting <option> to disable will mean that the script will not compare and display the files that will require modification.
Displaying Upgrade Steps
The --show_steps argument allows you to view a full list of upgrade steps between two specified versions of Squiz Matrix.
Usage of this script is as follows (please note that the database type must be specified when using this argument):
php matrix_upgrade.php --show_steps mysource_4-2-2 mysource_4-8-0 psql
php matrix_upgrade.php --show_steps mysource_4-2-2 mysource_4-8-0 oci
Upgrading your System
An example of how to use the upgrade script is shown below. In this example, we are upgrading a 3.28.6 system to Squiz Matrix 4.0.1. The --verbose argument has been used to display the list of upgrade steps that will be performed.
Tip: Before initiating the upgrade script, ensure that your server satisfies the minimum requirements for installation. For more information, refer to the Squiz Matrix Requirements.
php /automatic_upgrades/matrix_upgrade.php --verbose <system_root> mysource_4-0-1
Old ver. | New ver. | File | Description of steps
---------- | ---------- | -------------------- | --------------------------------------------------
3-28-6 | 4-0-0 | 3-28-6_to_4-0-0 | Disable search indexing
| | | Disable rollback
| | | Check out new code, using tag "mysource_4-0-0"
| | | File name length change from max 155 to 255 for sq_file_vers_file db
| | | table
| | | [3 queries: 2 , 1 ALTER TABLE]
| | | Run script: Change Matrix logos in login design, ees design, password
| | | change design
| | | Run script: Upgrade Funnelback config files for Funnelback binary engine 9.1
| | | TODO: Since Send Cacheable Header option is no longer assoicated with
| | | Caching status of Cache Manager, please verify the caching settings in
| | | type code /root node specific screen of Cache Manager.
| | | Run install step step_02
| | | Run install step compile_locale
| | | Run install step step_03
| | | Run install step compile_locale
| | | Change ownership of data and cache directories to "apache:apache"
| | | IF Rollback Mode was previously enabled:
| | | Enable rollback
| | | IF Search indexing was previously enabled:
| | | Enable search indexing
---------- | ---------- | -------------------- | --------------------------------------------------
4-0-0 | 4-0-1 | 4-0-0_to_4-0-1 | Disable search indexing
| | | Disable rollback
| | | Check out new code, using tag "mysource_4-0-1"
| | | Squiz Suite will sync products using a cron job rather than on commit.
| | | [3 queries: 3 ALTER TABLE]
| | | Run install step step_02
| | | Run install step compile_locale
| | | Run install step step_03
| | | Run install step compile_locale
| | | Change ownership of data and cache directories to "apache:apache"
| | | IF Rollback Mode was previously enabled:
| | | Enable rollback
| | | IF Search indexing was previously enabled:
| | | Enable search indexing
---------- | ---------- | -------------------- | --------------------------------------------------
Now upgrading from 3.28.6 to 4.0.0 [ Press ENTER to start ]
In this example, the 3.28.6 system will first be upgraded to 4.0.0 and then to 4.0.1. Pressing ENTER will begin the upgrade procedure.