Clustering

You can configure eZ Publish to store images, binary files and content-related caches in an Oracle database. This is typically useful if you want to run a site on a cluster of servers (refer to the "Clustering" section in the "Features" chapter of the eZ Publish Technical Manual for more information).

The following instructions explain how this can be done, assuming that you already have an eZ Publish site running on an Oracle database. The procedure consists of the following steps:

Clearing the caches (optional)
Modifying the "file.ini" settings
1. DB Cluster
2. DFS Cluster
Creating a new script for serving images
1. DB Cluster
2. DFS Cluster
Creating new database structures
Importing files to the database
Compiling the templates (optional)
Updating the Apache configuration
Restarting Apache and testing the site
Removing the imported files from the filesystem

These steps are very similar to the ones that are used when configuring eZ Publish to use clustering on a MySQL database, with a few differences in the first four steps, as described below.

1. Clearing the caches (optional)

It is recommended (but not required) to clear all eZ Publish caches before enabling the clustering functionality. This can be done by running the "bin/php/ezcache.php" script as shown below:

php bin/php/ezcache.php --clear-all --purge

After running the script, make sure that all cache files have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, remove them manually.

2. Modifying the "file.ini" settings

2.1. DB Cluster

Add the following lines to an override for the "file.ini" configuration file ("settings/override/file.ini.append.php" or "settings/siteaccess/ezwebin_site/file.ini.append.php" where "ezwebin_site" is the name of your siteaccess):

[ClusteringSettings]
FileHandler=eZDBFileHandler
DBBackend=eZDBFileHandlerOracleBackend
DBHost=
DBPort=
DBSocket=
DBName=ORCL
DBUser=scott
DBPassword=tiger
DBChunkSize=65535

Replace "ORCL", "scott" and "tiger" with the actual data:

Name of the Oracle instance (usually a simple name specified in your "tnsnames.ora" file)
User name
Password

In most cases these values will be the same as the "Database", "User" and "Password" settings specified in the [DatabaseSettings] block of your "site.ini.append.php" configuration file.

The "DBHost", "DBPort" and "DBSocket" settings can be left empty, since they are not used when running eZ Publish on an Oracle database.

Setting the "FileHandler" configuration directive to "eZDBFileHandler" will instruct eZ Publish to use the specified database for storing images, binary files and content-related caches. The "DBBackend" setting specifies the back-end to be used by the "ezdb" file handler. The settings above will instruct eZ Publish to use the back-end located in "extension/ezoracle/clusterfilehandlers/dbbackends/oracle.php".

The "DBChunkSize" setting determines the size of the blocks (in bytes) into which files are split when they are fetched from the database.

2.2. DFS Cluster

[ClusteringSettings]
FileHandler=eZDFSFileHandler

[eZDFSClusteringSettings]
MountPointPath=/media/nfs
DBBackend=eZDFSFileHandlerOracleBackend
DBHost=
DBPort=
DBSocket=
DBName=ORCL
DBUser=scott
DBPassword=tiger
DBConnectRetries=3
DBExecuteRetries=20

Replace "ORCL", "scott" and "tiger" with the actual data.

Note: Folder indicated in MountPointPath shouldn't contain anything but files handled by eZ Publish cluster, since files within this folder are maintained by cluster maintenance scripts, and can be potentially removed. If you need to store files here (i.e. custom cache files), be sure to use eZClusterFileHandler in your own PHP code.

3. Creating a new script for serving images

On a clustered installation, files from the var folder that are read through HTTP will be served by PHP. Your web-server (e.g Apache) will be instructed to use a specific PHP script, "index_cluster.php", for serving those files. From version 4.7, this file is common to all clustered installations.

In order to maximize performances, this script doesn't use the fully blown INI configuration system. Dedicated settings must be provided using either config.php, or config.cluster.php, at the root of your eZ Publish setup. Both files will lead to the same behaviour, but config.cluster.php is only included when serving requests through index_cluster.php, not index.php. The list of possible settings can be found in the config.php-RECOMMENDED file shipped with the release. The easiest way is to copy the relevant settings from this file to your own config.php.

3.1. DB Cluster

A typical config.php for a DB Oracle cluster would look like this:

<?php
define( 'CLUSTER_STORAGE_BACKEND', 'dboracle );
define( 'CLUSTER_STORAGE_HOST', '' );
define( 'CLUSTER_STORAGE_PORT', '' );
define( 'CLUSTER_STORAGE_USER', 'scott' );
define( 'CLUSTER_STORAGE_PASS', 'tiger' );
define( 'CLUSTER_STORAGE_DB', 'ORCL' );
define( 'CLUSTER_STORAGE_CHARSET', 'utf8' );
define( 'CLUSTER_STORAGE_GATEWAY_PATH', 'extension/ezoracle/clusterfilehandlers/gateways/db.php' );

3.2. DFS Cluster

A typical config.php for a DFS Oracle cluster would look like this:

<?php
define( 'CLUSTER_STORAGE_BACKEND', 'dfsoracle' );
define( 'CLUSTER_STORAGE_HOST', '' );
define( 'CLUSTER_STORAGE_PORT', '' );
define( 'CLUSTER_STORAGE_USER', 'scott' );
define( 'CLUSTER_STORAGE_PASS', 'tiger' );
define( 'CLUSTER_STORAGE_DB', 'ORCL' );
define( 'CLUSTER_STORAGE_CHARSET', 'utf8' );
define( 'CLUSTER_MOUNT_POINT_PATH', '/media/nfs' );
define( 'CLUSTER_STORAGE_GATEWAY_PATH', 'extension/ezoracle/clusterfilehandlers/gateways/dfs.php' );

Note: Make sure you specify the same database settings as indicated under the "[eZDFSClusteringSettings]" block in your "file.ini.append.php" configuration file.

4. Creating new database structures

You have to create some structures in the database manually. You'll find the needed definitions in the "oracle.php" file located in the "extension/ezoracle/clusterfilehandlers/dbbackends" or "extension/ezoracle/clusterfilehandlers/dfsbackends subdirectories. The definitions are placed inside comment blocks in the beginning of the file.

When using the SQL*Plus command line tool, be sure not to miss the ending slash ("/") in the last line of the PL/SQL code copied from the "oracle.php" file.

5. Importing files to the database

Refer to the "Clustering - Setting it up for an eZDBFileHandler " and "Clustering - Setting it up for an Setting it up for an eZDFSFileHandler " documentation pages for details.

6. Cronjobs

The cluster_maintenance cronjob is:

not needed when using the Oracle eZDB handler. All binary files are immediately deleted in the database
not effective when using the Oracle eZDFS handler. A separate script is provided to the same effect: extension/ezoracle/bin/php/oracleclusterbinarypurge.php
Please note that it can take a long time to run, as it has to scan the complete dfs mount point for expired files. It can put a lot of strain on the NFS server, too. Run it once with the --help option to see all available options for it and take advantage of those options to tune its usage to your needs.

Path

Table of contents