Manual Installation Guide

Squiz Matrix can be installed on your own hardware and using any operating system that supports the product's requirements. Manual installation is performed using our public CVS repository and checkout script. A web-based interface to the CVS repository is also provided at http://public-cvs.squiz.net/.

Automatic checkout script

A checkout script is available to install Squiz Matrix from a command-line invocation of CVS. This script runs under a Linux or a Mac environment and requires familiarity with using command line tools.

Instructions on how to use this script are given when running the script as follows:

$ sh checkout.sh

This script will check out Squiz Matrix based on a version number you supply into a dirrectory named "squiz_matrix". Version numbers reflect release versions. They are named the same way: mysource_4-xx-y. For example, if you want Squiz Matrix 4.0.4, the version number will be mysource_4-0-4.

In order to check out a copy of Squiz Matrix 4.0.4, run the script as follows:

$ sh checkout.sh mysource_4-0-4

Squiz Matrix may be installed to a new directory (other than "squiz_matrix"). In order to do so, the directory name should be specified as a second argument to the script. For example:

$ sh checkout.sh mysource_4-0-4 test_checkout

This will check out a copy of Squiz Matrix 4.0.4 to a directory named "test_checkout". The output of the script will be displayed as follows:

Checking out squiz matrix core ..
Checking out squiz matrix packages ..
Everything has been checked out into the test_checkout/ folder.
For installation instructions, please visit
http://matrix.squizsuite.net/quick-start-guide/manual-installation/

Installation instructions

Security Warning

Squiz Matrix should not be installed in a public web-accessible directory, like htdocs. Public web access should only be given to the directories that Squiz Matrix requires, as described in the Apache Aliases section below.

Database setup

Squiz Matrix requires a database for storing data. Before starting an installation, first ensure that you have created a database for Squiz Matrix to use.

We have short guides to help you create a database. Please select your database management system from the list below.

Important Information

The database installation guides will show you how to construct and set the database DSNs. A DSN is a connection string that Squiz Matrix uses to connect to the database. Please ensure you have followed the DB setup guide before continuing.

Basic Configuration Settings

Squiz Matrix comes with 4 installation scripts that need to be run in a particular order. The first script will initialise the main configuration file.

$ cd /home/websites/squiz_matrix
$ php install/step_01.php /home/websites/squiz_matrix

What step 1 of the installation did is create a configuration file for you. This is the main system configuration file and is located at /home/websites/squiz_matrix/data/private/conf/main.inc

You now need to edit this file and add some basic configuration settings.

$ vi data/private/conf/main.inc

The following configuration settings need to be completed as a minimum:

  • SQ_CONF_SYSTEM_ROOT_URLS
  • SQ_CONF_DEFAULT_EMAIL
  • SQ_CONF_TECH_EMAIL

The system root URLs are the URLs that you will use to access the Squiz Matrix system. The email addresses should both be set to your email address so you receive any errors or other email notifications from the system.

Examples of these configuration settings are shown below.

Note that the system root URLs should not contain the protocol (eg. HTTP) and each should be separated by a new-line. All system root URLs must be fully qualified domain names, so a system root URL such as "localhost" will not work correctly.

define('SQ_CONF_SYSTEM_ROOT_URLS', 'www.example.com
another.example.com/matrix');

define('SQ_CONF_DEFAULT_EMAIL', 'you@example.com');
define('SQ_CONF_TECH_EMAIL', 'you@example.com');

You will also need to add your database details to the db.inc file. In this file, each database connection is defined by an array of settings, including the data source name (DSN), which is provided in a different (PDO-compatible) format. The specific DSN format for each database is available from the setup guide for that database.

A typical db.inc on a PostgreSQL database system is shown below:

$db_conf = array (
        'db' => array (
                'DSN' => 'pgsql:dbname=squiz_matrix;host=db',
                'user' => 'matrix',
                'password' => '',
                'type' => 'pgsql',
               ),
        'db2' => array (
                'DSN' => 'pgsql:dbname=squiz_matrix;host=db',
                'user' => 'matrix',
                'password' => '',
                'type' => 'pgsql',
               ),
        'db3' => array (
                'DSN' => 'pgsql:dbname=squiz_matrix;host=db',
                'user' => 'matrix_secondary',
                'password' => '',
                'type' => 'pgsql',
               ),
        'dbcache' => NULL,
        'dbsearch' => NULL,
        );

return $db_conf;

The "dbsearch" database parameter should be populated with the database details of a replicated Squiz Matrix database - in DSN / user / password /type array format as shown above - to offload search index requests from the main DB server.

Initialise the Database Schema

The second installation script will initialise the Squiz Matrix database schema, creating database tables, views, functions and sequences.

$ php install/step_02.php /home/websites/squiz_matrix

Install the Core Asset Types

The third installation script installs the different types of assets into the system. It also creates some system assets, such as the Trash folder and the root user account.

The compile_locale.php script is run before and after this step to ensure all errors, warnings and system asset names are translated correctly.

$ php install/compile_locale.php /home/websites/squiz_matrix
$ php install/step_03.php /home/websites/squiz_matrix
$ php install/compile_locale.php /home/websites/squiz_matrix

Fix File System Permissions

Some directories of Squiz Matrix require read and write permission for the user that the Apache web server is run as. All other directories should be read-only for the Apache user.

The example below assumes your Apache web server is running as the user "apache" and with the group "apache" and that you own all the files in /home/websites/squiz_matrix.

$ chmod -R 755 /home/websites/squiz_matrix

$ cd /home/websites/squiz_matrix
$ chown -R apache:apache data cache
$ chmod -R g+w data cache

Create Apache Aliases

Now that Squiz Matrix is installed, we need to enable web access to the system. This is done using Apache aliases.

Locate your Apache alias file, typically httpd.conf, and create a new VirtualHost directive for Squiz Matrix. The recommended VirtualHost setup is as follows:

<VirtualHost *:80>
ServerName server.example.com
DocumentRoot /home/websites/squiz_matrix/core/web

Options -Indexes FollowSymLinks

<Directory /home/websites/squiz_matrix>
  Order deny,allow
  Deny from all
</Directory>
<DirectoryMatch "^/home/websites/squiz_matrix/(core/(web|lib)|data/public|fudge)">
  Order allow,deny
  Allow from all
</DirectoryMatch>
<DirectoryMatch "^/home/websites/squiz_matrix/data/public/assets">
  php_flag engine off
</DirectoryMatch>

<FilesMatch "\.inc$">
  Order allow,deny
  Deny from all
</FilesMatch>
<LocationMatch "/(CVS|\.FFV)/">
  Order allow,deny
  Deny from all
</LocationMatch>

Alias /__fudge   /home/websites/squiz_matrix/fudge
Alias /__data    /home/websites/squiz_matrix/data/public
Alias /__lib     /home/websites/squiz_matrix/core/lib
Alias /          /home/websites/squiz_matrix/core/web/index.php/
</VirtualHost>

Note that the order of each alias is important. You should replace server.example.com with the hostname of your server, as specified in the /etc/hosts file.  

Save the file and restart Apache. You should be now be able to access the frontend of Squiz Matrix using the URL you have configured in Apache. If all goes well, you will actually see a notice on the screen. This indicates that Squiz Matrix is running but you have not yet created any sites within the system.  

Cron Setup  

To allow the Squiz Matrix cron system to function, you need to edit the crontab file for the user that your web server runs as by running the following command:  

crontab -u apache -e  

Now add entries to invoke the Squiz Matrix cron scripts.   

*/15 * * * * php /home/websites/squiz_matrix/core/cron/run.php
0 0 * * * /home/websites/squiz_matrix/scripts/session_cleanup.sh /home/websites/squiz_matrix